> ## 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 all payslip data for an employee within a date range > Retrieves all payslip data for a specific employee within a specified date range. If no date range is provided, defaults to the last year from today. ## OpenAPI ````yaml /api-reference/specs/pay-api.yaml get /payslip/data/{employeeId} 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: /payslip/data/{employeeId}: get: tags: - Payslip summary: Get all payslip data for an employee within a date range description: >- Retrieves all payslip data for a specific employee within a specified date range. If no date range is provided, defaults to the last year from today. operationId: GetAllPayslipData parameters: - name: employeeId in: path required: true schema: type: string description: ID of the employee example: EMP01JPW80Q2B7Q9RGGRY29VGC8WM - name: beginDate in: query required: false schema: type: string format: date description: >- Start date for the payslip search range (YYYY-MM-DD format). Defaults to one year before endDate. example: '2024-01-01' - name: endDate in: query required: false schema: type: string format: date description: >- End date for the payslip search range (YYYY-MM-DD format). Defaults to today. example: '2024-12-31' responses: '200': description: All payslip data retrieved successfully content: application/json: schema: type: object allOf: - $ref: '#/components/schemas/ResponseBody' - properties: content: type: object properties: data: type: array items: $ref: '#/components/schemas/Payslip' example: message: text: All Payslip Data Retrieved token: getAllPayslipDataRetrieved content: data: - employeeDetails: id: EMP01JPW80Q2B7Q9RGGRY29VGC8WM name: title: Mr firstName: John lastName: Doe initials: JD address: line1: 123 Main Street line2: Apartment 4B city: London county: Greater London postcode: SW1A 1AA countryCode: GB birthDate: '1980-01-12' birthGender: Male payrollId: PAY123 employeeCode: EMP001 hoursWorkedCategory: Above30Hours taxCode: code: 1257L effectiveDate: '2024-04-06' reason: Standard tax code issuedBy: HMRC week1Month1: false nationalInsuranceCategory: A nationalInsuranceNumber: AB123456C passportNumber: '123456789' starterDetails: startDate: '2024-01-15' starterDeclaration: ThisIsMyOnlyJob secondedDetails: stayStatus: Stay183DaysOrMore eEACitizen: true ePM6: false alreadySentToHmrcFps: false studentDetails: studentLoanDetails: loanType: Plan2 startDate: '2020-09-01' endDate: '2023-06-30' postgraduateLoanDetails: loanType: PostgraduateLoan startDate: '2023-09-01' endDate: '2024-06-30' directorDetails: directorsNICType: Annual appointmentDate: '2024-01-15' leaverDetails: leavingDate: '2024-12-31' reason: Retirement issuedBy: Employer workplaceDetails: workplacePostcode: SW1A 1AA bankAccounts: - accountNumber: '12345678' sortCode: '123456' accountHolderName: John Doe isPrimaryPayrollAccount: true allocationPercentage: 100 employerDetails: id: LOAD_TEST organisationInformation: organisationId: ORG123456789 name: legalName: Acme Corporation Ltd tradingName: Acme Corp organisationType: LimitedCompany companyRegistrationNumber: '12345678' businessType: LimitedCompany registredOfficeAddress: line1: 456 Business Park line2: Suite 100 city: Manchester county: Greater Manchester postcode: M1 1AA countryCode: GB correspondenceAddress: line1: 456 Business Park line2: Suite 100 city: Manchester county: Greater Manchester postcode: M1 1AA countryCode: GB companyContactDetails: name: HR Department email: hr@acme.com phone: 0161 123 4567 primaryContactDetails: name: John Smith email: john.smith@acme.com phone: 0161 123 4568 createdBy: System createdDate: '2024-01-01T00:00:00.000Z' updatedBy: System updatedDate: '2024-01-01T00:00:00.000Z' taxReferenceNumbers: employerPayeReference: officeNumber: '123' referenceNumber: AB12345 accountsOfficeReference: 123PX00123456 selfAssessmentUniqueTaxpayerReference: '1234567890' corporationTaxReferenceUniqueTaxpayerReference: '1234567890' year: 2024 period: 1 payrollConfigId: 01JNR9P81W74HYCN35X1EEFDZE frequency: Monthly summaryItems: - id: PAYLINE-01JPW80Q2B5B76SQ2K56BZ3DHA description: Regular Hours amount: 306 type: Employee category: Earnings payElementId: base_salary date: '2024-02-28' forPeriod: gross: 306 grossTaxable: 306 grossNi: 306 tax: 45.2 ni: 25.3 employerNi: 35.4 studentLoan: 0 postgraduateLoan: 0 net: 235.5 yearToDate: gross: 306 grossTaxable: 306 grossNi: 306 tax: 45.2 ni: 25.3 employerNi: 35.4 studentLoan: 0 postgraduateLoan: 0 net: 235.5 createdDate: '2025-03-21T14:17:19.076Z' createdBy: System updatedDate: '2025-03-21T14:17:19.076Z' updatedBy: System status: Final paymentDate: null payPeriodStartDate: '2024-02-01' payPeriodEndDate: '2024-02-29' lateReason: null '400': description: Bad Request - Invalid date format or date range content: application/json: schema: $ref: '#/components/schemas/ResponseBody' example: message: text: Invalid beginDate format token: invalidBeginDateFormat tokenArguments: - name: beginDate value: invalid-date '404': description: Employee not found or payroll config not found content: application/json: schema: $ref: '#/components/schemas/ResponseBody' example: message: text: Employee Id Does Not Exist token: employeeIdDoesNotExist tokenArguments: - name: employeeId value: EMP01JPW80Q2B7Q9RGGRY29VGC8WM '500': description: Internal Server error content: application/json: schema: $ref: '#/components/schemas/ResponseBody' example: message: text: Internal Server Error for requestId req-123456 token: getPayslipDataInternalServerError tokenArguments: - name: requestId value: req-123456 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 Payslip: type: object properties: employeeDetails: $ref: '#/components/schemas/PayslipEmployeeDetailsDto' description: Employee details employerDetails: $ref: '#/components/schemas/PayslipEmployerDetailsDto' description: Employer details year: type: integer description: Year example: 2024 period: type: integer description: Period example: 2 payrollConfigId: type: string description: Payroll config id example: 01JNR9P81W74HYCN35X1EEFDZE frequency: type: string description: Frequency example: Monthly summaryItems: type: array items: $ref: '#/components/schemas/PayslipSummaryItemDto' description: Summary items forPeriod: $ref: '#/components/schemas/BaseValuesDto' yearToDate: $ref: '#/components/schemas/BaseValuesDto' forEmployment: $ref: '#/components/schemas/BaseValuesDto' createdDate: type: string description: Created date example: '2025-03-21T14:17:19.076Z' createdBy: type: string description: Created by example: System updatedDate: type: string description: Updated date example: '2025-03-21T14:17:19.076Z' updatedBy: type: string description: Updated by example: System status: type: string description: Status example: Final payslipMetadata: $ref: '#/components/schemas/PayslipMetadataDto' nullable: true description: Payslip metadata example: payslipMetadata: notes: This is a payslip note paymentDateOverwrite: '2024-02-28' paymentDate: type: string nullable: true description: Payment date example: null payPeriodStartDate: type: string description: Pay period start date example: '2024-02-01' payPeriodEndDate: type: string description: Pay period end date example: '2024-02-29' lateReason: type: string nullable: true description: Late reason enum: - NotionalPaymentToExpartByThirdPartyOrOverseasEmployer - NotionalPaymentOther - PaymentSubjectToClass1NicButP11dP9dForTax - MicroEmployerUsingTemporaryOnOrBeforeRelaxation - >- NoRequirementToMaintainADeductionsWorkingSheetOrImpossibleToReportWorkDoneOnTheDay - ReasonableExcuse - CorrectionToEarlierSubmission example: ReasonableExcuse alerts: type: array nullable: true description: >- Alerts raised for this payslip during calculation (e.g. missing bank account, NMW breach). Null or empty when no alerts apply. items: $ref: '#/components/schemas/PayslipAlertDto' lastEmailedAt: type: string nullable: true description: >- Timestamp of the last payslip email-send attempt (ISO 8601). Null if the payslip has never been emailed. example: '2026-06-24T10:00:00.000Z' lastEmailedTo: type: string nullable: true description: Email address the payslip was last sent to. example: jane.doe@example.com lastEmailedBy: type: string nullable: true description: >- User who triggered the last payslip email (or 'system' for automated sends). example: admin@example.com lastEmailedStatus: type: string nullable: true description: Outcome of the last payslip email-send attempt. enum: - Sent - Failed example: Sent lastEmailError: type: string nullable: true description: Reason the last payslip email failed. Null on success. example: Mailbox full versionId: type: string nullable: true description: >- Monotonic ULID stamped when this payslip's content was produced. Consumers use it as a freshness token: a payslip carrying a lower value than one already processed is stale and must not overwrite the newer state. Writes to the payslip itself are guarded on the same value. Null on payslips written before versioning existed — treat that as unknown, not as the oldest possible version. example: 01KZB4YMGGSKA1B3PFD5WJ5YFB 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' PayslipEmployeeDetailsDto: type: object properties: id: type: string description: Id example: EMP01JPW80Q2B7Q9RGGRY29VGC8WM name: $ref: '#/components/schemas/EmployeeNameDto' email: type: string description: Email address example: john.doe@example.com secondaryEmail: type: string nullable: true description: Secondary email address example: john.doe@example.com address: $ref: '#/components/schemas/AddressDto' nullable: true birthDate: type: string description: Birth date (YYYY-MM-DD) example: '1980-01-12' birthGender: type: string description: Birth gender (Male or Female) enum: - Male - Female example: Female payrollId: type: string nullable: true description: >- Payroll id (optional), only used for payroll runs PayId field in HMRC Full Payment Submission Report example: PAY123 employeeCode: type: string nullable: true description: Employee code. An optional identifier for the employee. example: EMP001 hoursWorkedCategory: type: string description: Weekly hours worked category. enum: - UpTo16Hours - From16To24Hours - From24To30Hours - Above30Hours - Other example: Above30Hours taxCode: $ref: '#/components/schemas/EmployeeTaxCodeDto' nationalInsuranceCategory: type: string description: National insurance category example: A nationalInsuranceNumber: type: string description: National insurance number example: AB123456C passportNumber: type: string nullable: true description: Passport number (optional) example: '123456789' starterDetails: $ref: '#/components/schemas/EmployeeStarterDetailsDto' studentDetails: $ref: '#/components/schemas/EmployeeStudentDetailsDto' nullable: true directorDetails: $ref: '#/components/schemas/EmployeeDirectorDetailsDto' nullable: true leaverDetails: $ref: '#/components/schemas/EmployeeLeaverDetailsDto' nullable: true workplaceDetails: $ref: '#/components/schemas/EmployeeWorkplaceDetailsDto' nullable: true bankAccounts: type: array items: $ref: '#/components/schemas/BankAccountDto' description: Bank accounts example: - accountNumber: '12345678' sortCode: '123456' accountHolderName: John Doe isPrimaryPayrollAccount: true allocationPercentage: 100 isPaymentAfterLeaving: type: boolean default: false description: >- This payslip pays someone who had already left and been given their P45. HMRC requires a 0T week 1/month 1 tax code, sends the payment on the FPS with the payment-after-leaving indicator set alongside the original leaving date, and forbids issuing a second P45. example: false PayslipEmployerDetailsDto: type: object properties: id: type: string description: Organisation id as per our platform example: LOAD_TEST organisationInformation: $ref: '#/components/schemas/OrganisationInformationDto' taxReferenceNumbers: $ref: '#/components/schemas/TaxReferenceNumbersDto' PayslipSummaryItemDto: type: object properties: id: type: string description: Unique identifier for the summary item example: PAYLINE-01JPW80Q2B5B76SQ2K56BZ3DHA description: type: string description: Description of the item example: Regular Hours amount: type: number format: decimal description: Amount for this item (payRate * units) example: 306 type: type: string enum: - Employee - Employer description: >- Indicate if this line is linked to the employee or employer. 0 is Employee and 1 is Employer example: '0' category: type: string enum: - Earning - Deduction - Informational description: Category of the item example: Earnings payRate: type: number format: decimal description: Pay rate for the item example: 10.5 payElementId: type: string description: Pay element id example: base_salary unitName: type: string description: Unit name enum: - Hour - Day - Week - Month - Year - Fixed - Informational - Percentage unitType: type: string enum: - Amount - Percentage default: Amount nullable: true description: >- The unit type for calculation. Amount uses payRate * units, Percentage uses payRate * (units / 100). Defaults to Amount if not provided. units: type: number description: Units chargeRate: type: number description: Charge rate nullable: true chargeUnits: type: number example: 1 chargeValue: type: number format: decimal nullable: true description: The charge value times the charge units example: 100 chargeDescription: type: string nullable: true description: Charge description for billing. date: type: string description: Date of the item example: '2024-02-28' isNetDeduction: type: boolean description: Is net deduction example: false tags: type: array items: $ref: '#/components/schemas/TagDto' nullable: true originalValue: type: number format: decimal nullable: true description: >- The original deduction amount before protected earnings adjustment. Shows what should have been deducted when deduction is reduced or zero. lineItemSequence: type: integer nullable: true description: Line item sequence number for court orders courtOrderId: type: string nullable: true description: Court order ID for court order line items courtOrderType: type: string nullable: true description: Court order type (e.g., DEA, AEO Priority, CMS DEO, etc.) canEdit: type: boolean description: >- Indicates whether this summary item can be edited. Court order items are not editable. example: true eligibility: $ref: '#/components/schemas/EligibilityDto' nullable: true description: >- Eligibility flags for this pay element (court orders, pensions, etc.) paymentDetails: $ref: '#/components/schemas/PaymentDetailsDto' nullable: true description: >- Payment details (BACS information) that can override default employee bank account clientId: type: string description: Client ID example: CLIENT-001 nullable: true poNumber: type: string nullable: true description: Purchase order number for billing purposes example: PO-2025-001 attachments: type: array items: $ref: '#/components/schemas/AttachmentResponseDto' nullable: true description: >- List of attachments with download URLs (only present when attachments exist) invoiceId: type: string nullable: true description: Invoice id when this line item has been allocated to an invoice. billingStatus: type: string enum: - None - Allocated - Disabled default: None description: Billing status for billable line items. calculationFlags: $ref: '#/components/schemas/PayslipSummaryItemCalculationFlagsDto' nullable: true description: >- Eligibility flags propagated from the source pay element. Downstream consumers (journal, billing, ledgers) use these to apportion per-element costs without re-reading the pay element config. wasReducedByProtectedEarnings: type: boolean default: false description: >- Whether this deduction line was reduced by the court order protected-earnings cap. tax: type: number format: decimal nullable: true description: >- This line's share of forPeriod.tax (PAYE). Null when the line is not taxable; 0 when taxable but the apportioned share is zero this period. Σ across all items equals forPeriod.tax (penny-perfect via Hamilton's largest-remainder method). employeeNi: type: number format: decimal nullable: true description: >- This line's share of forPeriod.ni (employee NI). Null when not Niable; 0 when eligible but the share is zero. Σ = forPeriod.ni. employeePension: type: number format: decimal nullable: true description: >- This line's share of forPeriod.pension (employee pension). Null when not pensionable; 0 when eligible but the share is zero. In SalarySacrifice mode this is 0 on every item because forPeriod.pension is 0 — the contribution lives on pensionContributionsByType[SalarySacrifice] and pensionSacrificeAmount on the synthetic sacrifice item. studentLoan: type: number format: decimal nullable: true description: >- This line's share of forPeriod.studentLoan. Null when not taxable; 0 when eligible but the share is zero. Σ = forPeriod.studentLoan. postgraduateLoan: type: number format: decimal nullable: true description: >- This line's share of forPeriod.postgraduateLoan. Same eligibility as tax. Σ = forPeriod.postgraduateLoan. employerNi: type: number format: decimal nullable: true description: >- This line's share of forPeriod.employerNi. Null when neither Niable nor EmployerOnly; 0 when eligible but the share is zero. Σ = forPeriod.employerNi. employerClass1ANi: type: number format: decimal nullable: true description: >- This line's share of forPeriod.employerClass1ANI (employer Class 1A NI on BIKs). Null when not Class 1A niable; 0 when eligible but the share is zero (Class 1A is normally settled annually on P11D, not per-pay-period). employerPension: type: number format: decimal nullable: true description: >- This line's share of forPeriod.employerPension. Null when not pensionable; 0 when eligible but the share is zero. Σ = forPeriod.employerPension. apprenticeshipLevy: type: number format: decimal nullable: true description: >- This line's share of forPeriod.apprenticeshipLevy. Same eligibility as employerNi. Σ = forPeriod.apprenticeshipLevy. employmentAllowance: type: number format: decimal nullable: true description: >- Historical only: per-item Employment Allowance slices are no longer written. Retained on summary items created while per-payslip apportionment existed (NeoPayroll 1.4.x); null on items written since. The run-level figure lives on the pay run's totalBalances. apprenticeshipLevyAllowance: type: number format: decimal nullable: true description: >- Historical only: per-item Apprenticeship Levy allowance slices are no longer written. Retained on summary items created while per-payslip apportionment existed (NeoPayroll 1.4.x); null on items written since. The run-level figure lives on the pay run's totalBalances. pensionSacrificeAmount: type: number format: decimal nullable: true description: >- The sacrificed amount on this line in SalarySacrifice pension schemes. Populated only on the internal_pension_salary_sacrifice synthetic item when the pension type is SalarySacrifice; null on every other item. 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 PayslipMetadataDto: type: object required: - notes properties: notes: type: string description: Notes to be added or updated for the payslip example: Additional holiday pay included for this period nullable: true paymentDateOverwrite: type: string description: Payment date overwrite for the payslip example: '2024-02-28' nullable: true PayslipAlertDto: type: object required: - code - severity properties: code: type: string description: Alert code identifying the rule that fired enum: - MissingBankAccount - NationalMinimumWageBreach - NiCategoryChanged - LeaverOnThisPayRun - PaymentAfterLeaving example: MissingBankAccount severity: type: string description: Alert severity enum: - Info - Warning - Error example: Warning context: type: object nullable: true description: >- Optional structured details about the alert. For NationalMinimumWageBreach this includes age, ageBracket, requiredRate, effectiveRate, nmwHours and nmwAmount. For NiCategoryChanged this includes to, effectiveDate (yyyy-MM-dd) and, when resolvable, from. For LeaverOnThisPayRun this includes leavingDate (yyyy-MM-dd) and, when the cessation missed its own pay run, reportedLate. For PaymentAfterLeaving this includes leavingDate (yyyy-MM-dd) and the taxCode applied. additionalProperties: type: string ValidationIssueArgument: type: object properties: name: type: string value: type: string EmployeeNameDto: type: object required: - firstName - lastName properties: firstName: type: string example: John middleName: type: string nullable: true example: Edward lastName: type: string example: Smith title: type: string nullable: true example: Mr AddressDto: type: object properties: line1: type: string nullable: true example: 123 Main Street line2: type: string nullable: true example: Apt 4B city: type: string nullable: true example: London county: type: string nullable: true example: Greater London postcode: type: string nullable: true example: SW1A 1AA countryCode: type: string default: GB description: >- ISO 3166-1 alpha-2 country code. Defaults to "GB" when omitted or blank. example: GB EmployeeTaxCodeDto: type: object required: - code properties: code: type: string description: The tax code for the employee. example: 1257L effectiveDate: type: string nullable: true description: >- The effective date of the tax code, if none is set, created date is used. example: '2024-04-06' reason: type: string description: Reason for the tax code change example: Standard tax code issuedBy: type: string description: 'Who issued the tax code change. Valid values: ''HMRC'', ''Employer''' example: HMRC week1Month1: type: boolean description: Whether the tax code is week1Month1, meaning basis non cumulative example: false EmployeeStarterDetailsDto: type: object required: - startDate - starterDeclaration - alreadySentToHmrcFps properties: startDate: type: string description: The start date of the employee. example: '2024-01-15' starterDeclaration: type: string description: >- The starter declaration of the employee. Use 'ThisIsMyFirstJobSince6thApril', 'ThisIsMyOnlyJob', or 'IHaveAnotherJobOrPension' for a new starter. Use 'None' for an existing employee who has already been reported to HMRC (for example, one migrated mid-year from another payroll provider); in that case alreadySentToHmrcFps must be true. example: ThisIsMyOnlyJob enum: - ThisIsMyFirstJobSince6thApril - ThisIsMyOnlyJob - IHaveAnotherJobOrPension - None secondedDetails: $ref: '#/components/schemas/EmployeeSecondedDetailsDto' nullable: true alreadySentToHmrcFps: type: boolean description: >- Whether the employee's starter details have already been reported to HMRC on an FPS. Set to false for a new starter (the starter declaration is reported on the next FPS). Set to true for an existing employee already reported to HMRC; this is required when starterDeclaration is 'None'. example: false EmployeeStudentDetailsDto: type: object description: The student details of the employee properties: studentLoanDetails: $ref: '#/components/schemas/EmployeeStudentLoanDetailsDto' nullable: true description: The details of the student loan postgraduateLoanDetails: $ref: '#/components/schemas/EmployeePostgraduateLoanDetailsDto' nullable: true description: The details of the postgraduate loan example: studentLoanDetails: loanType: Plan2 startDate: '2010-09-01' endDate: '2025-07-31' postgraduateLoanDetails: loanType: PostgraduateLoan startDate: '2015-09-01' endDate: '2028-07-31' EmployeeDirectorDetailsDto: type: object properties: directorsNICType: type: string description: >- Director's National Insurance contribution calculation method. Put 'Annual' if you're using the standard annual method of work out the director's National Insurance contributions, or 'Alternative' if you're using the alternative method example: Annual appointmentDate: type: string description: The date of appointment of the employee's director. example: '2024-01-15' endDate: type: string nullable: true description: The date the employee ceased to be a director. example: '2025-03-31' EmployeeLeaverDetailsDto: type: object properties: leavingDate: type: string description: The date the employee left the company. example: '2024-12-31' reason: type: string nullable: true description: The reason the employee left the company. example: Retirement issuedBy: type: string nullable: true description: The entity that issued the leaver certificate. example: Employer reportedToHmrc: type: boolean description: >- Whether the leaving date has been sent to HMRC on an FPS. Set only on a real submission, never on a preview. example: false default: false finalisedOnPayslip: type: boolean description: >- Whether the leaving date is carried by a finalised payslip on a locked pay run. Until this is true the employee stays on the payroll-config roster, so a cessation recorded after its own pay run closed is still picked up and reported on the next one. example: false default: false EmployeeWorkplaceDetailsDto: type: object properties: workplaceId: type: string example: workplace_001 workplaceName: type: string example: Head Office address: $ref: '#/components/schemas/AddressDto' BankAccountDto: type: object required: - accountNumber - sortCode - allocationPercentage properties: accountNumber: type: string pattern: ^\d{6,8}$ minLength: 6 maxLength: 8 description: >- UK bank account number. Must be 6-8 digits (zero-padded to 8 for BACS). example: '12345678' sortCode: type: string pattern: ^\d{6}$ minLength: 6 maxLength: 6 description: >- UK bank sort code. Must be 6 digits. Hyphens are stripped before validation. example: '123456' isPrimaryPayrollAccount: type: boolean nullable: true description: At least one bank account must be set as primary. example: true accountHolderName: type: string nullable: true description: >- Name of the account holder. Optional — falls back to employee name for payment files. example: John Smith allocationPercentage: type: integer minimum: 1 maximum: 100 description: >- Percentage of salary allocated to this account. All accounts must total 100%. example: 100 OrganisationInformationDto: type: object allOf: - $ref: '#/components/schemas/UpdatableOrganisationInformationDto' - type: object properties: organisationId: type: string description: Organisation id of the organisation example: org_123 createdBy: type: string description: >- Created by of the organisation information. This is the user who created the organisation information example: user_123 createdDate: type: string format: date-time description: >- Created date of the organisation information. This is the date and time when the organisation information was created example: '2025-01-01T00:00:00Z' updatedBy: type: string description: >- Updated by of the organisation information. This is the user who updated the organisation information example: user_456 updatedDate: type: string format: date-time description: >- Updated date of the organisation information. This is the date and time when the organisation information was updated example: '2025-01-02T00:00:00Z' required: - organisationId - createdBy - createdDate - updatedBy - updatedDate TaxReferenceNumbersDto: type: object properties: employerPayeReference: $ref: '#/components/schemas/PayeReferenceNumberDto' accountsOfficeReference: type: string description: Accounts office reference. example: 123PX00123456 selfAssessmentUniqueTaxpayerReference: type: string nullable: true description: Self assessment unique taxpayer reference. example: '1234567890' corporationTaxReferenceUniqueTaxpayerReference: type: string nullable: true description: Corporation tax reference unique taxpayer reference. example: '1234567890' required: - employerPayeReference - accountsOfficeReference TagDto: type: object required: - name - group - value properties: name: type: string example: FullTime group: type: string example: EmploymentType value: type: string example: FullTime EligibilityDto: type: object description: Eligibility flags for different types (court orders, pensions, etc.) properties: courtOrders: $ref: '#/components/schemas/CourtOrderEligibilityDto' nullable: true description: Court order eligibility flags for this pay element example: courtOrders: cmsDeo: true dea: true aeoPriority: false aeoNonPriority: false ctaeo: false ea: false mcaeo: false PaymentDetailsDto: type: object description: >- Payment details (BACS information) that can override default employee bank account properties: accountName: type: string nullable: true description: Account name example: CMS Central Account accountNumber: type: string nullable: true description: Account number example: '12345678' sortCode: type: string nullable: true description: Sort code example: 12-34-56 paymentReference: type: string nullable: true description: >- Payment reference to include with BACS payment (e.g., court order remittance reference) example: CMS-2025-UK01 paymentCategory: type: string nullable: true description: Payment category for categorizing payment details enum: - CourtOrders example: CourtOrders AttachmentResponseDto: type: object properties: id: type: string description: The unique identifier for the attachment lineItemId: type: string description: The unique identifier of the associated payroll line item filename: type: string description: The original filename of the attachment contentType: type: string description: The MIME type of the file fileSize: type: integer format: int64 description: The size of the file in bytes uploadedDate: type: string format: date-time description: The date and time the file was uploaded (ISO 8601 format) uploadedBy: type: string description: The identifier of the user who uploaded the file downloadUrl: type: string format: uri description: Pre-signed URL for downloading the file (expires after 60 minutes) downloadUrlExpiresAt: type: string format: date-time description: The expiration date/time of the download URL (ISO 8601 format) PayslipSummaryItemCalculationFlagsDto: type: object description: >- Eligibility flags propagated from the source pay element, used by downstream consumers (journal, billing, ledgers) to apportion per-element costs without re-reading pay element config. properties: niType: type: string enum: - Niable - NonNiable - EmployerOnly description: >- NI eligibility. Niable = both employee and employer NI apply; EmployerOnly = employer NI only (typical for some benefits in kind); NonNiable = no NI applies. payType: type: string enum: - Payable - Deductible - Informational description: >- Whether this line adds to gross (Payable), reduces it (Deductible), or is reporting-only (Informational). isPensionable: type: boolean description: Whether this line contributes to gross pensionable earnings. accrueHoliday: type: boolean description: Whether this line counts toward holiday accrual. isClass1ANiable: type: boolean description: >- Whether this line is subject to employer Class 1A NI (typically benefits in kind). taxType: type: string enum: - Taxable - NonTaxable nullable: true description: >- Tax eligibility. Added in NeoPayroll 1.3.0 — payslips persisted before that release may have this as null on legacy items. required: - niType - payType - isPensionable - accrueHoliday - isClass1ANiable 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 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 EmployeeSecondedDetailsDto: type: object required: - eEACitizen - ePM6 properties: stayStatus: type: string nullable: true description: >- Indicates the stay status of the employee Allowed values: 'Stay183DaysOrMore', 'StayLessThan183Days', or 'InOutUK'. example: Stay183DaysOrMore eEACitizen: type: boolean description: Indicates if the employee is an EEA citizen. example: true ePM6: type: boolean description: Indicator that this is an EPM 6 (modified) scheme example: false EmployeeStudentLoanDetailsDto: type: object description: The details of the student loan properties: loanType: type: string nullable: true description: Type of student loan enum: - Plan1 - Plan2 - Plan4 - Plan5 example: Plan2 startDate: type: string nullable: true description: The start date of the student loan example: '2010-09-01' endDate: type: string nullable: true description: The end date of the student loan example: '2025-07-31' example: loanType: Plan2 startDate: '2010-09-01' endDate: '2025-07-31' EmployeePostgraduateLoanDetailsDto: type: object description: The details of the postgraduate loan properties: loanType: type: string nullable: true description: Type of postgraduate loan enum: - PostgraduateLoan example: PostgraduateLoan startDate: type: string nullable: true description: The start date of the postgraduate loan example: '2015-09-01' endDate: type: string nullable: true description: The end date of the postgraduate loan example: '2028-07-31' example: loanType: PostgraduateLoan startDate: '2015-09-01' endDate: '2028-07-31' UpdatableOrganisationInformationDto: type: object properties: name: $ref: '#/components/schemas/OrganisationNameDto' organisationType: type: string description: Organisation type of the organisation enum: - Parent - Subsidiary - Independent - Franchise - Branch example: LimitedCompany companyRegistrationNumber: type: string description: >- Company Registration Number (CRN), also known as a Companies House number, is a unique identifier assigned to a company when it's registered with Companies House. It's essentially a way to distinguish one company from another and verify its existence example: '12345678' businessType: type: string description: Business type of the organisation enum: - LimitedCompany - LimitedLiabilityPartnership - SoleTrader - Partnership - Charity - PublicSector example: LimitedCompany registredOfficeAddress: $ref: '#/components/schemas/AddressDto' correspondenceAddress: $ref: '#/components/schemas/AddressDto' companyContactDetails: $ref: '#/components/schemas/ContactDetailsDto' primaryContactDetails: $ref: '#/components/schemas/ContactDetailsDto' required: - name - organisationType - companyRegistrationNumber - businessType - registredOfficeAddress - correspondenceAddress - companyContactDetails - primaryContactDetails - bankAccount PayeReferenceNumberDto: type: object properties: officeNumber: type: string description: HMRC Office number. example: '123' referenceNumber: type: string description: Company's unique reference number. example: AB12345 required: - officeNumber - referenceNumber CourtOrderEligibilityDto: type: object description: Court order eligibility flags for each order type properties: cmsDeo: type: boolean description: >- Eligible for CMS DEO (Child Maintenance Service Deduction from Earnings Order) example: true dea: type: boolean description: Eligible for DEA (Direct Earnings Attachment) example: true aeoPriority: type: boolean description: Eligible for AEO Priority (Attachment of Earnings Order - Priority) example: true aeoNonPriority: type: boolean description: >- Eligible for AEO Non-Priority (Attachment of Earnings Order - Non-Priority) example: true ctaeo: type: boolean description: Eligible for CTAEO (Council Tax Attachment of Earnings Order) example: true ea: type: boolean description: Eligible for EA (Earnings Attachment) example: false mcaeo: type: boolean description: >- Eligible for MCAEO (Maintenance Calculation Attachment of Earnings Order) example: false 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 OrganisationNameDto: type: object properties: legalName: type: string description: Legal name of the organisation example: Acme Corporation Ltd tradingName: type: string nullable: true description: Trading name of the organisation example: Acme Corp ContactDetailsDto: type: object properties: name: type: string description: Name of the contact. example: HR Department email: type: string description: Email of the contact. example: hr@acme.com phone: type: string nullable: true description: Phone of the contact. example: 0161 123 4567 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). ````