> ## 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. # Get payroll run(lock) data ## OpenAPI ````yaml /api-reference/specs/pay-api.yaml get /payroll/{payrollConfigId}/{year}/{period} 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: Payroll - name: Payroll lines - name: PayrollConfig - name: Pay Elements - name: Calculator - name: Payslip - name: RTI - name: YearEnd - name: Organisation paths: /payroll/{payrollConfigId}/{year}/{period}: get: tags: - Payroll summary: Get payroll run(lock) data operationId: GetPayroll parameters: - name: payrollConfigId in: path required: true schema: type: string - name: year in: path required: true schema: type: integer description: The year in format yyyy - name: period in: path required: true schema: type: integer description: The period of the pay run (1, 2, 3... etc) responses: '200': description: Payroll Run data found content: application/json: schema: type: object allOf: - $ref: '#/components/schemas/ResponseBody' - properties: content: type: object properties: data: $ref: '#/components/schemas/PayrollRunEntryDto' '400': description: Invalid path parameters content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '404': description: Payroll config id not found content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/ResponseBody' components: schemas: 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' messageToken: type: string PayrollRunEntryDto: type: object properties: organisationId: type: string description: The organisation ID example: LOAD_TEST payrollConfigId: type: string description: The payroll config ID example: 01JNR9P81W74HYCN35X1EEFDZE paymentDate: type: string format: date description: The payment date in format yyyy-mm-dd example: '2024-05-06' year: type: integer description: The year in format yyyy example: 2024 period: type: string description: The period in format mm example: '2' frequency: type: string description: >- The pay frequency, Valid values: 'Annual', 'Monthly', 'FourWeekly', 'Fortnightly', 'Weekly', 'Daily'. enum: - Annual - Monthly - FourWeekly - Fortnightly - Weekly - Daily example: Monthly periodStartDate: type: string description: The start date of the tax period in format yyyy-mm-dd example: '2024-05-06' periodEndDate: type: string description: The end date of the tax period in format yyyy-mm-dd example: '2024-06-05' payPeriodStartDate: type: string description: The start date of the pay period in format yyyy-mm-dd example: '2024-05-01' payPeriodEndDate: type: string description: The end date of the pay period in format yyyy-mm-dd example: '2024-05-31' status: type: string description: >- The status of the payroll run, Valid values: 'Completed', 'Processing'. enum: - Completed - Processing - Open example: Completed lockStatus: type: string description: 'The status of the payroll run, Valid values: "Locked", "Unlocked".' enum: - Locked - Unlocked example: Locked totalEmployees: type: integer description: >- The total number of employees in the payroll run, including employees with no payroll line items. example: 10 totalSucceeded: type: integer description: >- The total number of employees in the payroll run that have successfully been processed. example: 10 totalFailed: type: integer description: >- The total number of employees in the payroll run that have failed to be processed. example: 0 createdBy: type: string description: The user ID of who created the payroll run example: System createdDate: type: string description: The date and time the payroll run was created example: '2025-03-21T14:17:16.126Z' updatedBy: type: string description: The user ID of who updated the payroll run example: System updatedDate: type: string description: The date and time the payroll run was updated example: '2025-03-21T14:17:19.320Z' completedDate: type: string nullable: true description: The date and time the payroll run was completed example: '2025-03-21T14:17:19.320Z' lockedBy: type: string nullable: true description: The user ID of who locked the payroll run example: System lockedDate: type: string nullable: true hmrcDetails: $ref: '#/components/schemas/PayrollRunEntryHmrcDetailsDto' description: The HMRC details for the payroll run totalBalances: $ref: '#/components/schemas/PayrollRunBalancesDto' description: The balances for the payroll run 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' PayrollRunEntryHmrcDetailsDto: type: object properties: fullPaymentSubmissionReportDetails: $ref: '#/components/schemas/PayrollRunEntryFpsHmrcDetailsDto' description: The details of the full payment submission report PayrollRunBalancesDto: type: object description: >- Payroll run balances containing base values and statutory payments reclaims properties: baseValues: $ref: '#/components/schemas/BaseValuesDto' description: Base values for the payroll run statutoryPaymentsReclaims: type: object description: Dictionary of statutory payments reclaims by type additionalProperties: $ref: '#/components/schemas/StatutoryPaymentsReclaimDto' example: SSP: amount: 100 type: StatutorySickPay SMP: amount: 150 type: StatutoryMaternityPay required: - baseValues - statutoryPaymentsReclaims ValidationIssueArgument: type: object properties: name: type: string value: type: string PayrollRunEntryFpsHmrcDetailsDto: type: object properties: hmrcFpsSubmissionId: type: string nullable: true description: The id of the FPS HMRC submission example: null hmrcFpsSubmissionDate: type: string nullable: true description: The date and time the FPS HMRC submission was sent example: null hmrcFpsReportStatus: type: string description: The status of the FPS HMRC submission example: NotSent enum: - NotSent - Sending - Sent - Failed - GeneratingPreview - PreviewReady correlationId: type: string nullable: true description: The correlation ID of the FPS HMRC submission example: '1234567890' errors: type: array items: type: string description: The errors of the FPS HMRC submission example: - Error 1 - Error 2 submissionBody: type: string description: The XML of the FPS submission serialized to a string submissionResponse: type: string description: The XML of the FPS submission response serialized to a string previewS3Key: type: string nullable: true description: The S3 key for the preview XML (separate from submission S3Key) example: null submissionDownloadUrl: type: string nullable: true description: Pre-signed S3 URL to download the submitted FPS body XML directly example: null previewDownloadUrl: type: string nullable: true description: Pre-signed S3 URL to download the preview XML directly example: null 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 nullable: true grossPensionable: type: number format: decimal description: Gross pensionable pay example: 306 grossForCourtOrders: type: number format: decimal description: Gross pay for court orders example: 306 nullable: true 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: Pension contribution 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 nullable: true employerPension: type: number format: decimal description: Employer pension contribution 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 nullable: true description: National Insurance band breakdown additionalProperties: type: object additionalProperties: $ref: '#/components/schemas/NiCalculationResultDto' statutory: type: object nullable: true description: Statutory payments breakdown additionalProperties: type: number format: decimal example: SSP: 0 SMP: 0 pensionContributionsByType: type: object nullable: true description: Pension contributions broken down by pension type additionalProperties: type: number format: decimal 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 (NeoPayroll 1.4.x) 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 (NeoPayroll 1.4.x) retain their historical share. Per-employee views are derived from the run-level figure. example: 0 statutoryRecovery: type: object nullable: true 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. additionalProperties: $ref: '#/components/schemas/StatutoryPaymentsReclaimDto' 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 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 required: - reclaimed - nicCompensationRecovered NiCalculationResultDto: type: object required: - employeeNi - employerNi - totalNi - grossForEmployeeNi - grossForEmployerNi properties: employeeNi: type: number format: decimal employerNi: type: number format: decimal totalNi: type: number format: decimal grossForEmployeeNi: type: number format: decimal grossForEmployerNi: type: number format: decimal bandResults: type: object nullable: true additionalProperties: $ref: '#/components/schemas/NiBandResultDto' 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 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). ````