> ## 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. # List the earlier versions of a payslip > Needs permission pay-run:read. Lists the earlier versions of an employee's payslip for a year and period: one per lock cycle its pay run was unlocked from, oldest first. A payslip whose pay run was never unlocked has no versions. The live payslip is GET /payslip/data/{employeeId}/{year}/{period}. ## OpenAPI ````yaml /api-reference/specs/pay-api.yaml get /payslip/data/{employeeId}/{year}/{period}/versions 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: /payslip/data/{employeeId}/{year}/{period}/versions: get: tags: - Payslip summary: List the earlier versions of a payslip description: >- Needs permission pay-run:read. Lists the earlier versions of an employee's payslip for a year and period: one per lock cycle its pay run was unlocked from, oldest first. A payslip whose pay run was never unlocked has no versions. The live payslip is GET /payslip/data/{employeeId}/{year}/{period}. operationId: ListPayslipVersions parameters: - name: year in: path required: true schema: type: integer format: int32 description: Year of the payslip example: 2026 - name: period in: path required: true schema: type: integer format: int32 description: Pay period number within the year example: 7 - name: employeeId in: path required: true schema: type: string description: ID of the employee example: EMP01JPW80Q2B7Q9RGGRY29VGC8WM - name: frequency in: query required: false schema: type: string enum: - Annual - Monthly - FourWeekly - Fortnightly - Weekly - Daily - Quarterly - BiAnnually description: >- Optional payment frequency override. When provided, overrides the frequency from the employee's payroll config. example: Monthly - $ref: '#/components/parameters/Request-Id' responses: '200': description: >- The payslip versions were retrieved successfully; empty when the pay run was never unlocked content: application/json: schema: type: object allOf: - $ref: '#/components/schemas/ResponseBody' - properties: content: type: object properties: data: type: array items: $ref: '#/components/schemas/PayslipVersionSummaryDto' '400': description: Invalid frequency parameter content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '500': description: Internal Server error content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/ResponseBody' components: parameters: Request-Id: name: Request-Id in: header required: false description: >- Optional. Your id for this request: it is carried into every log line about it, so quote it when you contact support. schema: type: string schemas: ResponseBody: type: object required: - message properties: message: $ref: '#/components/schemas/MessageWithTokenResponse' description: >- A readable message about the outcome and a stable token a client can branch on. content: type: object required: - metadata properties: data: description: >- The resource or list the request asked for; left out when there is none. metadata: type: object required: - dateFormat - dateTimeFormat properties: dateFormat: type: string description: The format of the dates in this response, yyyy-MM-dd. dateTimeFormat: type: string description: >- The format of the timestamps in this response, yyyy-MM-ddTHH:mm:ss.fffZ in UTC. paginationToken: type: string nullable: true description: >- Send this value back as the paginationToken query parameter to get the next page; absent when there are no more pages. description: >- The date formats the response uses and, on a paged list, the token for the next page. description: >- The data the request returns with its metadata; left out on a response that carries no data, such as most errors. validationIssues: type: array items: $ref: '#/components/schemas/ValidationIssue' nullable: true description: >- Each field the request was refused for and why; left out when the request was not refused for its fields. PayslipVersionSummaryDto: type: object description: >- One earlier version of a payslip: the payslip as it stood when its pay run was locked for the given lock cycle, kept when that run was unlocked. Versions are never changed or removed. required: - lockCycle - supersededAt - supersededBy - status - gross - net - tax - forPeriod - updatedDate properties: lockCycle: type: integer format: int32 description: The lock cycle this version belongs to (1 = the first lock) supersededAt: type: string description: When the version was superseded, UTC supersededBy: type: string description: Who unlocked the pay run supersededReason: type: string nullable: true description: The reason given for the unlock, when one was given status: type: string enum: - Preview - Final - Reopened description: The payslip status at the time (Final) gross: type: number format: decimal description: Gross pay for the period as it stood net: type: number format: decimal description: Net pay for the period as it stood tax: type: number format: decimal description: Tax for the period as it stood forPeriod: $ref: '#/components/schemas/BaseValuesDto' description: >- The whole period as it stood: gross, net, tax, NI, pension and the rest, so a version can be compared line by line without reading it in full updatedDate: type: string description: When the payslip was last written before it was superseded versionId: type: string nullable: true description: The payslip's freshness token at the time, when it had one MessageWithTokenResponse: type: object required: - text - token properties: text: type: string description: The message in English, ready to show to a user. token: type: string description: >- A stable snake_case key for the message, so a client can show its own wording or a translation instead of text. tokenArguments: type: array items: $ref: '#/components/schemas/ValidationIssueArgument' nullable: true description: >- Values to fill into the client's own wording for token, such as the request id; absent when the message has none. 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. required: - field - reason - reasonToken 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 items: $ref: '#/components/schemas/ValidationIssueArgument' nullable: true description: >- Values to fill into the client's own wording for reasonToken; absent when the reason has none. BaseValuesDto: type: object properties: gross: type: number format: decimal description: Gross pay example: 306 grossTaxable: type: number format: decimal description: Gross taxable pay example: 306 grossNi: type: number format: decimal description: Gross pay for National Insurance purposes example: 306 grossForEmployerNi: type: number format: decimal description: Gross pay for employer National Insurance purposes example: 306 grossForEmployerClass1ANi: type: number format: decimal description: Gross pay for employer Class 1A National Insurance purposes example: 306 grossPensionable: type: number format: decimal description: Gross pensionable pay example: 306 grossForCourtOrders: type: number format: decimal description: Gross pay for court orders example: 306 tax: type: number format: decimal description: Tax amount example: 45.2 ni: type: number format: decimal description: Employee National Insurance contribution example: 25.3 pension: type: number format: decimal description: >- The member's pension movement for the slice this object covers (period, year to date or employment to date): contributions deducted from pay, including additional voluntary contributions, minus any opt-out refunds paid back. Negative in a period that refunds more than it deducts. Salary-sacrifice contributions are employer money and live in employerPension, never here. Reconciles with the pension summary items: read one source or the other, never both. example: 0 employerNi: type: number format: decimal description: Employer National Insurance contribution example: 35.4 employerClass1ANI: type: number format: decimal description: Employer Class 1A National Insurance contribution example: 35.4 employerPension: type: number format: decimal description: >- The employer's pension contributions for the slice, including salary-sacrifice amounts (sacrificed pay is the employer's contribution), minus any salary-sacrifice opt-out refunds. example: 0 studentLoan: type: number format: decimal description: Student loan repayment example: 0 postgraduateLoan: type: number format: decimal description: Postgraduate loan repayment example: 0 net: type: number format: decimal description: Net pay after deductions including net deductions example: 235.5 netDeductions: type: number format: decimal description: Net deductions applied to the net pay example: 0 totalPayable: type: number format: decimal description: Total payable example: 235.5 totalEmployerCost: type: number format: decimal description: Total employer cost example: 306 niBand: type: object additionalProperties: $ref: '#/components/schemas/NiCalculationResultDto' description: National Insurance band breakdown statutory: type: object additionalProperties: type: number format: decimal description: Statutory payments breakdown example: SSP: 0 SMP: 0 pensionContributionsByType: type: object additionalProperties: type: number format: decimal description: >- Pension contributions broken down by pension type. Contributions only: opt-out refunds never appear here, so read pensionRefundsByType for those. Net member movement per scheme = contributions minus refunds. example: NetPayArrangement: 0 ReliefAtSource: 0 SalarySacrifice: 0 qualifyingEarningsForPension: type: number format: decimal description: Qualifying earnings for pension calculation example: 0 apprenticeshipLevy: type: number format: decimal description: >- Per-payslip gross apprenticeship levy attributable to this period. Equal to 0.5 percent of grossForEmployerNi when the organisation pays AL, otherwise 0. The org-level £15,000 annual allowance is applied at the EPS level, not deducted per payslip — so summing this across a pay run gives the gross levy used for reconciliation against the organisation's monthly AL balance. example: 1.53 employmentAllowance: type: number format: decimal description: >- Employment Allowance used by this pay run — an employer-level figure, populated on the pay run's totalBalances when the run completes. Not stamped on individual payslips: payslip forPeriod/yearToDate values are always 0 for payslips generated after per-payslip apportionment was removed; payslips written while it existed retain their historical share. Per-employee views (journal Employment Allowance lines) are derived from the run-level figure. example: 0 apprenticeshipLevyAllowance: type: number format: decimal description: >- Apprenticeship Levy allowance (annual £15,000 pot, accrued monthly) used by this pay run — an employer-level figure, populated on the pay run's totalBalances when the run completes. Not stamped on individual payslips: payslip forPeriod/yearToDate values are always 0 for payslips generated after per-payslip apportionment was removed; payslips written while it existed retain their historical share. Per-employee views are derived from the run-level figure. example: 0 statutoryRecovery: type: object additionalProperties: $ref: '#/components/schemas/StatutoryPaymentsReclaimDto' description: >- Per-statutory-type recovery this payslip contributes to the EPS. Keys are the StatutoryTypeEnum string values (StatutoryMaternityPay, StatutoryPaternityPay, SharedParentalPay, StatutoryAdoptionPay, StatutoryParentalBereavementPay, StatutoryNeonatalCarePay). Statutory Sick Pay is never recoverable per HMRC DANSP37000 and is omitted from this map. example: StatutoryMaternityPay: reclaimed: 100 nicCompensationRecovered: 8.5 isEmpty: type: boolean nullable: true description: >- Whether every value in this record is zero, as judged by the producer. A pay run's totalBalances is written asynchronously after the run completes and reads back as an all-zero record until then, so a consumer cannot tell "not written yet" from "genuinely nil" by inspecting the figures. Null means this producer did not supply the flag — treat it as unknown, never as false. example: false pensionRefundsByType: type: object additionalProperties: type: number format: decimal description: >- The MEMBER contributions paid back through this period, broken down by pension type. Absent unless a refund happened. The refund also appears as a Payable internal_pension_{scheme}_refund summary item and nets forPeriod.pension, so the period scalar can be negative in a refund period. The employer half is reported separately in employerPensionRefundsByType. example: ReliefAtSource: 146.76 employerPensionRefundsByType: type: object additionalProperties: type: number format: decimal description: >- The EMPLOYER contributions reversed by an opt-out refund, broken down by pension type. Absent unless a refund happened. Employer money never passes through the member's net pay (the scheme repays the employer directly), but it is netted off employerPension for the period, and therefore off the monthly balance, the organisation year-to-date figures and the journal cost slices built from it. This field is the disclosure of what was reversed, so read it to explain a balance, never to subtract again. example: ReliefAtSource: 110.07 ValidationIssueArgument: type: object required: - name - value properties: name: type: string description: The name of the value, as a client's wording refers to it. value: description: The value itself, as a string, number or other JSON value. NiCalculationResultDto: type: object properties: employeeNi: type: number format: decimal description: Employee National Insurance under this NI category letter. employerNi: type: number format: decimal description: Employer National Insurance under this NI category letter. totalNi: type: number format: decimal description: Employee and employer National Insurance added together. grossForEmployeeNi: type: number format: decimal description: >- Earnings that employee National Insurance was worked out on under this letter. grossForEmployerNi: type: number format: decimal description: >- Earnings that employer National Insurance was worked out on under this letter. bandResults: type: object additionalProperties: $ref: '#/components/schemas/NiBandResultDto' description: >- The same figures split by National Insurance band, keyed by band name. example: employeeNi: 290.1 employerNi: 310.25 totalNi: 600.35 grossForEmployeeNi: 3500 grossForEmployerNi: 3500 bandResults: PT-UEL: grossInBand: 2000 employeeNiForBand: 180 employerNiForBand: 220 UEL+: grossInBand: 500 employeeNiForBand: 110.1 employerNiForBand: 90.25 StatutoryPaymentsReclaimDto: type: object properties: reclaimed: type: number format: decimal description: Amount reclaimed this tax year example: 100 nicCompensationRecovered: type: number format: decimal description: National Insurance contribution compensation recovered this tax year example: 50 NiBandResultDto: type: object properties: grossInBand: type: number format: decimal description: Gross pay in this NI band example: 12570 employeeNiForBand: type: number format: decimal description: Employee NI contribution for this band example: 0 employerNiForBand: type: number format: decimal description: Employer NI contribution for this band example: 0 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.