> ## Documentation Index > Fetch the complete documentation index at: https://docs.stardex.com/llms.txt > Use this file to discover all available pages before exploring further. # Create person compensation > Create a compensation history record for a person. Use this for current, desired, or minimum compensation details. If `job_id` is provided, the person must already be a candidate on that job. ## OpenAPI ````yaml /api-reference/openapi-v1.json post /v1/persons/{id}/compensations openapi: 3.1.0 info: title: Stardex API (v1) version: 1.0.0 description: >- Stardex ATS API — manage candidates, jobs, companies, and recruiting workflows. servers: - url: https://api.stardex.ai description: Production API server security: - bearerAuth: [] tags: - name: Persons description: Manage person records — contacts, work history, and custom fields. - name: Jobs description: Manage job postings — pipeline stages, team members, and custom fields. - name: Candidates description: Manage candidate records and pipeline stage transitions. - name: Companies description: Browse and retrieve company records. - name: Lists description: Create, search, and retrieve saved person and company lists. - name: Person Activities description: Create and manage activity records (notes, emails, meetings) for persons. - name: Team Members description: List team members for use in search filters and assignments. - name: Custom Fields description: Retrieve custom field definitions and tag options for search filters. paths: /v1/persons/{id}/compensations: post: tags: - Persons summary: Create person compensation description: >- Create a compensation history record for a person. Use this for current, desired, or minimum compensation details. If `job_id` is provided, the person must already be a candidate on that job. operationId: createPersonCompensation parameters: - in: path name: id required: true schema: type: string description: Person UUID requestBody: content: application/json: schema: $ref: '#/components/schemas/PersonCompensationCreateRequest' responses: '201': description: Compensation created content: application/json: schema: $ref: '#/components/schemas/PersonCompensationResponse' example: success: true data: id: 678e9012-e34d-56f7-a890-123456789012 compensation_type: desired currency_code: USD current_compensation_base: 200000 current_compensation_bonus: null equity_percent: null equity_amount: null compensation_year: 2026 total_estimated_compensation: 200000 note: Target base salary discussed with the candidate. job_id: null job_name: null created_at: '2026-05-27T21:30:00Z' updated_at: '2026-05-27T21:30:00Z' '400': description: Validation error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '404': description: Resource not found content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error components: schemas: PersonCompensationCreateRequest: type: object properties: job_id: type: - string - 'null' format: uuid description: >- Associated job UUID, if this compensation is specific to a job candidacy. current_compensation_base: type: - number - 'null' minimum: 0 description: Base salary amount. current_compensation_bonus: type: - number - 'null' minimum: 0 description: Bonus amount. compensation_type: type: - string - 'null' enum: - desired - actual - minimum description: >- Type of compensation: desired for expectations, actual for current or historical compensation, or minimum for a required floor. currency_code: type: - string - 'null' minLength: 3 maxLength: 3 description: >- ISO 4217 currency code (e.g. "USD", "EUR"). Defaults to USD when omitted. equity_percent: type: - number - 'null' minimum: 0 maximum: 100 description: Equity grant as a percentage. equity_amount: type: - number - 'null' minimum: 0 description: Equity grant as a fixed amount. compensation_year: type: - integer - 'null' minimum: 1900 maximum: 3000 description: >- The year this compensation applies to (e.g. 2025 for historical compensation). total_estimated_compensation: type: - number - 'null' minimum: 0 description: Total estimated annual compensation. note: type: - string - 'null' description: >- Free-text notes about the compensation package, constraints, or preferences. PersonCompensationResponse: type: object properties: success: type: boolean enum: - true data: $ref: '#/components/schemas/PersonCompensation' required: - success - data PersonCompensation: type: object properties: id: type: string format: uuid description: Compensation record UUID. compensation_type: type: - string - 'null' enum: - desired - actual - minimum description: 'Type of compensation: "desired", "actual", or "minimum".' currency_code: type: - string - 'null' description: ISO 4217 currency code (e.g. "USD", "EUR"). Defaults to USD. current_compensation_base: type: - number - 'null' description: Base salary amount. current_compensation_bonus: type: - number - 'null' description: Bonus amount. equity_percent: type: - number - 'null' description: Equity grant as a percentage. equity_amount: type: - number - 'null' description: Equity grant as a fixed amount. compensation_year: type: - number - 'null' description: >- The year this compensation applies to (e.g. 2025 for historical comp). total_estimated_compensation: type: - number - 'null' description: Total estimated annual compensation (base + bonus + equity). note: type: - string - 'null' description: Free-text compensation notes. job_id: type: - string - 'null' format: uuid description: Associated job UUID, if this compensation is job-specific. job_name: type: - string - 'null' description: Title of the associated job. created_at: type: string description: ISO 8601 timestamp. updated_at: type: string description: ISO 8601 timestamp. required: - id - compensation_type - currency_code - current_compensation_base - current_compensation_bonus - equity_percent - equity_amount - compensation_year - total_estimated_compensation - note - job_id - job_name - created_at - updated_at securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Authenticate with a Bearer token: API key, OAuth token, or session token. ````