> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowpayroll.ai/llms.txt > Use this file to discover all available pages before exploring further. # Set the employee's annual salary from an effective date > Adds a version of the employee's annual salary effective from the given date, leaving earlier versions in place so past periods still resolve the salary that applied then. Sending the same effectiveFrom again replaces that version rather than appending another, so retries and corrections are safe; to move a version to a different date, delete it and add the new one. An amount of 0 states that no salary is paid from that date. Any open pay run the employee is on is recalculated. Responds with the full history. ## OpenAPI ````yaml /api-reference/specs/pay-api.yaml put /employees/{employeeId}/salary openapi: 3.0.3 info: title: FlowPayroll API description: >- API for payroll management, including payroll upload, lock, HMRC submission, employee management version: 0.1.0 servers: - url: https://api.sandbox.flowpayroll.ai/v1 security: - XAuthToken: [] XOrgId: [] tags: - name: Employees description: >- Create, retrieve, update, and delete employee records, and look them up by NI number or payroll ID. - name: Starters & leavers description: Set and clear starter and leaver details, individually or in bulk. - name: Tax codes description: >- Manage employee tax codes and query the effective tax code and NI category on a given date. - name: NI & identifiers description: Manage NI categories, National Insurance numbers, and payroll IDs. - name: Student loans description: Start and end student and postgraduate loans. - name: Payroll setup description: Assign an employee's payroll config and set opening balances. - name: Salary description: >- The employee's effective-dated annual salary history: read it, add or correct a version from a date, and remove one. The Salary API pro-rates this history onto each pay run. - name: Payroll - name: Payroll lines - name: PayrollConfig - name: Pay Elements - name: Calculator - name: Payslip - name: RTI - name: YearEnd - name: Organisation paths: /employees/{employeeId}/salary: put: tags: - Salary summary: Set the employee's annual salary from an effective date description: >- Adds a version of the employee's annual salary effective from the given date, leaving earlier versions in place so past periods still resolve the salary that applied then. Sending the same effectiveFrom again replaces that version rather than appending another, so retries and corrections are safe; to move a version to a different date, delete it and add the new one. An amount of 0 states that no salary is paid from that date. Any open pay run the employee is on is recalculated. Responds with the full history. operationId: PutSalary parameters: - name: employeeId in: path required: true schema: type: string description: The ID of the employee requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpsertEmployeeSalaryRequestDto' responses: '200': description: Salary saved content: application/json: schema: type: object allOf: - $ref: '#/components/schemas/ResponseBody' - properties: content: type: object properties: data: $ref: >- #/components/schemas/EmployeeSalaryHistoryResponseDto '400': description: Invalid request data content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '404': description: Employee not found content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '500': description: An internal server error occurred content: application/json: schema: $ref: '#/components/schemas/ResponseBody' components: schemas: UpsertEmployeeSalaryRequestDto: type: object description: Set the employee's annual salary from a given effective date. required: - effectiveFrom - annualSalary properties: effectiveFrom: type: string format: date description: The date this salary takes effect. Format YYYY-MM-DD. example: '2026-04-06' annualSalary: type: number format: decimal minimum: 0 description: >- The annual salary in pounds. 0 states that no salary is paid from this date. example: 52000 reason: type: string nullable: true maxLength: 500 description: Optional note on why the salary changed, shown in the history. example: Annual review ResponseBody: type: object properties: message: $ref: '#/components/schemas/MessageWithTokenResponse' content: type: object properties: data: type: object nullable: true metadata: type: object nullable: true properties: dateFormat: type: string default: yyyy-MM-dd dateTimeFormat: type: string default: yyyy-MM-ddTHH:mm:ss.fffZ paginationToken: type: string nullable: true validationIssues: type: array items: $ref: '#/components/schemas/ValidationIssue' EmployeeSalaryHistoryResponseDto: type: object description: >- The full effective-dated salary history of an employee, oldest first, with the version in force today. required: - versions properties: versions: type: array description: Every version, oldest first. items: $ref: '#/components/schemas/EmployeeSalaryVersionDto' inForce: nullable: true description: >- The version in force today; null when every version is still in the future. allOf: - $ref: '#/components/schemas/EmployeeSalaryVersionDto' MessageWithTokenResponse: type: object properties: text: type: string token: type: string tokenArguments: type: array items: $ref: '#/components/schemas/ValidationIssueArgument' ValidationIssue: type: object description: > Field validation item. `reasonToken` is a stable snake_case key for i18n or custom client messages; `reason` is the default English text from the API. properties: field: type: string description: Dot-path of the field (e.g. name.firstName, address.line1). reason: type: string description: Default human-readable message. reasonToken: type: string description: Machine-readable error identifier (snake_case). reasonTokenArguments: type: array nullable: true items: $ref: '#/components/schemas/ValidationIssueArgument' EmployeeSalaryVersionDto: type: object description: An effective-dated salary version with audit metadata. required: - effectiveFrom - annualSalary properties: effectiveFrom: type: string format: date example: '2026-04-06' annualSalary: type: number format: decimal description: The annual salary in pounds in force from effectiveFrom. example: 52000 reason: type: string nullable: true example: Annual review createdDate: type: string createdBy: type: string updatedDate: type: string updatedBy: type: string ValidationIssueArgument: type: object properties: name: type: string value: type: string securitySchemes: XAuthToken: type: apiKey in: header name: X-Auth-Token description: Access token obtained from OAuth2 client credentials flow XOrgId: type: apiKey in: header name: X-Org-Id description: >- Organisation to scope the request to. Required when the principal can access more than one organisation; optional for single-organisation principals (the authorizer resolves it automatically). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.