> ## 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. # Search the organisation's employees on any field > Needs permission employee:read. Filters on any employee field (every operator a field's type allows; tags and other repeated fields match any or all values), dated values such as the tax code and NI category as on `asAt`, sorting, the fields to answer, and paging with how many match in all, so a list can say "50 of 6,000". Fields your role cannot read are neither answered nor matched. `GET /employee-fields` lists every field you can filter on. To see your own change straight after a write, send the employee and the `updatedDate` your write returned in `consistentWith`. ## OpenAPI ````yaml /api-reference/specs/pay-api.yaml post /employees/search 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/search: post: tags: - Employees summary: Search the organisation's employees on any field description: >- Needs permission employee:read. Filters on any employee field (every operator a field's type allows; tags and other repeated fields match any or all values), dated values such as the tax code and NI category as on `asAt`, sorting, the fields to answer, and paging with how many match in all, so a list can say "50 of 6,000". Fields your role cannot read are neither answered nor matched. `GET /employee-fields` lists every field you can filter on. To see your own change straight after a write, send the employee and the `updatedDate` your write returned in `consistentWith`. operationId: SearchEmployees parameters: - $ref: '#/components/parameters/Request-Id' requestBody: description: What to match, sort and answer; an empty body lists every employee required: false content: application/json: schema: $ref: '#/components/schemas/EmployeeSearchRequestDto' responses: '200': description: Employees found content: application/json: schema: type: object allOf: - $ref: '#/components/schemas/ResponseBody' - properties: content: type: object properties: data: $ref: '#/components/schemas/EmployeeSearchResultDto' '400': description: The search cannot be answered as sent; the message says why 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: An internal server error occurred content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '503': description: >- The search could not catch up with your own write; retry after the Retry-After seconds 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: EmployeeSearchRequestDto: type: object description: >- Employees of the organisation matching every filter, a page at a time, with how many match in all. properties: asAt: type: string nullable: true format: date description: >- The date dated values and where each employee stands are read for, yyyy-MM-dd; today when omitted. example: '2026-11-05' status: type: string enum: - All - Active - Leaver - FutureLeaver description: >- `Leaver`: marked a leaver or left before the date. `FutureLeaver`: active with a leaving date on or after it. `All` when omitted. example: Active search: type: string nullable: true description: Name, email, employee code or payroll ID containing this, any case. example: jane filters: type: array items: $ref: '#/components/schemas/EmployeeSearchFilterDto' nullable: true description: Every one must hold. sort: type: array items: $ref: '#/components/schemas/EmployeeSearchSortDto' nullable: true description: Then by last name and first name. fields: type: array items: type: string nullable: true description: >- The fields to answer; a group such as `address` answers all of it. Everything your role can read when omitted. example: - name - department - taxCode limit: type: integer format: int32 description: At most this many, from 1 to 500. example: 100 offset: type: integer format: int32 description: How many matches to skip. example: 0 consistentWith: type: array items: $ref: '#/components/schemas/EmployeeWrittenVersionDto' nullable: true description: >- Employees you have just written: the answer waits until it reflects them, or answers 503 with Retry-After when it cannot within ten seconds. 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. EmployeeSearchResultDto: type: object description: A page of employees. required: - items - total - hasMore properties: items: type: array items: $ref: '#/components/schemas/EmployeeSearchItemDto' description: The page, in order. total: type: integer format: int32 description: How many employees match in all. example: 6000 hasMore: type: boolean description: Whether more match after this page. example: true EmployeeSearchFilterDto: type: object description: A condition on one employee field. required: - field - operator properties: field: type: string description: >- The field's path as `GET /employee-fields` lists it: dots between objects, `[]` for a list, `{}` for a map (`tags[].value`), or a dated value (`taxCode`, `niCategory`, `salary`, `director`, `studentLoan`, `postgraduateLoan`) read for `asAt`. example: department operator: type: string enum: - Equals - NotEquals - In - NotIn - Contains - StartsWith - GreaterThan - GreaterThanOrEqual - LessThan - LessThanOrEqual - Between - IsEmpty - IsNotEmpty - ContainsAll description: >- How the field is compared. `ContainsAll` is for a field with several values; `Contains` and `StartsWith` for text; `GreaterThan`, `LessThan` and `Between` for numbers and dates. example: In values: type: array items: type: string nullable: true description: >- The values compared with; dates are yyyy-MM-dd. None for `IsEmpty` and `IsNotEmpty`, two for `Between`. example: - Engineering - Sales EmployeeSearchSortDto: type: object description: An order to list employees in. required: - field properties: field: type: string description: A field that holds one value. example: starterDetails.startDate descending: type: boolean description: Largest or latest first. example: true EmployeeWrittenVersionDto: type: object description: An employee you have just written, so the answer reflects the write. required: - employeeId properties: employeeId: type: string description: The employee. example: 01JD8Y7Q3N4M5P6R7S8T9V0W1X updatedDate: type: string nullable: true description: >- The `updatedDate` your write returned; null when it deleted the employee. example: '2026-11-05T10:00:00.000Z' 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. EmployeeSearchItemDto: type: object description: One employee, holding only the fields asked for that your role can read. required: - employeeId - status - employee - inForce properties: employeeId: type: string description: The employee. example: 01JD8Y7Q3N4M5P6R7S8T9V0W1X status: type: string enum: - Active - Leaver - FutureLeaver description: Where the employee stands on the date asked about. example: Active employee: $ref: '#/components/schemas/EmployeeDto' description: >- The employee as `GET /employees/{employeeId}` answers it, holding only the fields asked for (every field when `fields` is omitted) that your role can read; any other field is absent, required or not. Year to date (`earningsToDatePerYear`, `directorEarningsToDatePerYear`) is never included: read it from `GET /employees/{employeeId}`. `isLeaver` is read for `asAt`, as `status` is. inForce: $ref: '#/components/schemas/EmployeeInForceDto' description: The dated values on the date asked about. 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. EmployeeDto: allOf: - $ref: '#/components/schemas/UpdatableEmployeeDto' - type: object required: - id - payrollConfigId - starterDetails properties: id: type: string description: The unique identifier for the employee. example: emp_12345 payrollId: type: string nullable: true description: >- Payroll ID used as the payId field in HMRC FPS submissions. Updated via PUT /employees/{id}/payroll-id. example: PAY123 payrollIdChanged: $ref: '#/components/schemas/EmployeePayIdChangedDto' nullable: true description: >- The employee's previous payroll ID, kept when the payroll ID is replaced and reported to HMRC on the FPS as a payroll ID change. payrollConfigId: type: string description: The payroll config the employee is assigned to. example: payroll_config_001 starterDetails: $ref: '#/components/schemas/EmployeeStarterDetailsDto' description: >- The employment start date, and the starter declaration or secondment details reported to HMRC on the FPS. leaverDetails: $ref: '#/components/schemas/EmployeeLeaverDetailsDto' nullable: true description: >- The leaving date and reason once the employee is marked as a leaver; null otherwise. isLeaver: type: boolean nullable: true description: >- Whether the employee has left: marked as a leaver, or their leaving date has passed. Read only. earningsToDatePerYear: type: object additionalProperties: $ref: '#/components/schemas/EmployeeEarningsToDateDto' description: >- Computed year-to-date earnings (opening balance + accumulated payslips). Read-only. openingBalance: type: object additionalProperties: $ref: '#/components/schemas/EmployeeEarningsToDateDto' description: >- Opening balance for this employment. Updated via PUT /employees/{id}/opening-balance. openingBalanceDirector: type: object additionalProperties: $ref: '#/components/schemas/DirectorEarningsToDateDto' description: >- Opening balance for director earnings. Updated via PUT /employees/{id}/opening-balance. Only NI-relevant fields. directorEarningsToDatePerYear: type: object additionalProperties: $ref: '#/components/schemas/DirectorEarningsToDateDto' description: >- Computed year-to-date director earnings for NI calculation (opening balance + accumulated payslips). Read-only. salaryHistory: allOf: - $ref: '#/components/schemas/EmployeeSalaryHistoryResponseDto' nullable: true description: >- The effective-dated salary history, oldest first, with the version in force today. Managed via PUT /employees/{id}/salary; `salary` is the amount of the version in force. createdDate: type: string nullable: true format: date-time description: When the employee record was created, as a UTC date and time. example: '2023-01-15T10:00:00Z' createdBy: type: string nullable: true description: The user who created the employee record. example: admin@company.com updatedDate: type: string nullable: true format: date-time description: >- When the employee record was last changed, as a UTC date and time. example: '2023-06-01T12:00:00Z' updatedBy: type: string nullable: true description: The user who last changed the employee record. example: hr@company.com EmployeeInForceDto: type: object description: >- The employee's dated values on the date asked about. A value is null when none is in force then, or when your role cannot read it. properties: taxCode: type: string nullable: true description: The tax code in force. example: 1257L niCategory: type: string nullable: true description: The National Insurance category letter in force. example: A salary: type: number format: decimal nullable: true description: The annual salary in force. example: 32000 director: type: boolean nullable: true description: >- True while the employee is a director for National Insurance, through the end of the tax year their directorship ends in. example: true studentLoan: type: string enum: - Plan1 - Plan2 - Plan4 - Plan5 description: The student loan plan being repaid. example: Plan2 postgraduateLoan: type: string enum: - PostgraduateLoan description: The postgraduate loan being repaid. example: PostgraduateLoan UpdatableEmployeeDto: type: object required: - name - email - birthGender - birthDate - hoursWorkedCategory properties: name: $ref: '#/components/schemas/EmployeeNameDto' description: >- The employee's name as reported to HMRC; the first and last names are required, each 1 to 35 characters starting with a letter. email: type: string format: email description: >- The employee's primary email address; required, it must be a valid email address and is the address payslip emails are sent to. example: john.smith@company.com taxCodesPerYear: type: object additionalProperties: type: array items: $ref: '#/components/schemas/EmployeeTaxCodeDto' description: Tax codes for the employee per tax year example: '2025': - code: 1257L effectiveDate: '2025-04-06' reason: HMRC Update issuedBy: HMRC week1Month1: false niDetails: $ref: '#/components/schemas/EmployeeNiDto' nullable: true description: National Insurance details for the employee birthGender: type: string enum: - Male - Female description: The gender reported to HMRC for the employee on the FPS; required. example: Male phone: type: string nullable: true description: >- The employee's primary phone number, stored as sent and carried on the payslip's recipient details. birthDate: type: string format: date description: >- The employee's date of birth (YYYY-MM-DD); required, and the employee must be between 12 and 120 years old. example: '1985-07-23' maritalStatus: type: string enum: - Single - Married - Divorced - Widowed - CivilPartnership - FormerCivilPartnership - SurvivorCivilPartnership description: >- The employee's marital status; optional, and refused when it is not one of the listed values. example: Married hoursWorkedCategory: type: string enum: - UpTo16Hours - From16To24Hours - From24To30Hours - Above30Hours - Other description: >- The band of normal weekly hours the employee works, reported to HMRC on the FPS; required. example: Above30Hours salary: type: number format: decimal nullable: true description: > Deprecated as input on PUT and PATCH: record salary changes with PUT /employees/{employeeId}/salary instead, which keeps an effective-dated history the pay run pro-rates from. While still accepted, a value that differs from the salary in force today updates the most recent salary version in place; null or absent leaves the history untouched. Accepted unchanged on POST /employees, where it becomes the first salary version effective from the start date. Always populated on responses as the annual salary in force today (or the earliest version when every version is still in the future). Will be removed from input in a future version. example: 35000 employeeCode: type: string nullable: true description: Employee code. An optional identifier for the employee. example: EMP001 secondaryEmail: type: string nullable: true format: email description: >- An optional second email address for the employee, checked as an email address when sent. example: john.secondary@company.com address: $ref: '#/components/schemas/AddressDto' nullable: true description: >- The employee's home address, reported to HMRC on the FPS; line1, line2, county and city are its address lines. bankAccounts: type: array items: $ref: '#/components/schemas/BankAccountDto' nullable: true description: >- The employee's bank accounts; exactly one must be the primary payroll account, and with more than one their allocation percentages must add up to 100. studentDetails: $ref: '#/components/schemas/EmployeeStudentDetailsDto' nullable: true description: >- The employee's student loan and postgraduate loan plans, with the dates each starts and ends. tags: type: array items: $ref: '#/components/schemas/TagDto' nullable: true description: >- Tags on the employee, copied onto the employee details of each payslip. previousEmployment: type: object additionalProperties: $ref: '#/components/schemas/PreviousEmploymentEarningsDto' description: >- Earnings from a previous employer in the same tax year. Used for cumulative tax calculations only. Does not affect FPS reporting. example: '2026': grossTaxable: 15000 tax: 3000 gender: type: string nullable: true description: >- The employee's gender as free text, stored and returned as sent; birthGender is the value reported to HMRC. example: Male secondaryPhone: type: string nullable: true description: >- An optional second phone number for the employee, stored and returned as sent. passportNumber: type: string nullable: true description: >- The employee's passport number, reported to HMRC on the FPS; 1 to 35 letters, numbers, spaces and standard punctuation. example: '123456789' previousNames: type: array items: type: string nullable: true description: >- Names the employee was previously known by; each must meet the same rules as a name and none may repeat. example: - John Doe directorDetails: $ref: '#/components/schemas/EmployeeDirectorDetailsDto' nullable: true description: >- Set when the employee is a director: the director's NI calculation method, appointment date and, once it ends, the end date. isIrregularEmployment: type: boolean nullable: true description: >- Whether the employee is paid on an irregular pattern, reported to HMRC on the FPS; treated as false when absent. example: false isOffPayrollWorker: type: boolean nullable: true description: >- Whether the worker is engaged under the off-payroll working rules (IR35), reported to HMRC on the FPS; treated as false when absent. example: false workplaceDetails: $ref: '#/components/schemas/EmployeeWorkplaceDetailsDto' nullable: true description: >- Where the employee works; its workplace postcode is reported to HMRC on the FPS. workingDays: $ref: '#/components/schemas/WorkingDaysConfigurationDto' nullable: true description: >- The employee's working pattern in force today; its dated history is kept by the employee working pattern endpoints. partnerDetails: $ref: '#/components/schemas/EmployeePartnerDetailsDto' nullable: true description: >- The employee's partner, reported to HMRC on the FPS with the first payment of Shared Parental Pay. department: type: string nullable: true description: >- The employee's department as free text, copied onto the employee details of each payslip. example: Engineering jobTitle: type: string nullable: true description: >- The employee's job title as free text, copied onto the employee details of each payslip. example: Software Engineer EmployeePayIdChangedDto: type: object description: Records that the employee's payroll id changed, for RTI continuity. properties: oldPayId: type: string nullable: true description: The payroll id this employee had before it was changed. EmployeeStarterDetailsDto: type: object required: - startDate - starterDeclaration properties: startDate: type: string description: The start date of the employee. example: '2024-01-15' starterDeclaration: type: string enum: - ThisIsMyFirstJobSince6thApril - ThisIsMyOnlyJob - IHaveAnotherJobOrPension - None 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 secondedDetails: $ref: '#/components/schemas/EmployeeSecondedDetailsDto' nullable: true description: >- For an employee seconded to work in the UK, the secondment details reported to HMRC in place of a starter declaration; cannot be sent with starterDeclaration. 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 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 leaver details have been reported to HMRC. example: false finalisedOnPayslip: type: boolean description: Whether the leaver has been reported on a finalised payslip. EmployeeEarningsToDateDto: type: object description: The earnings to date for the employee properties: gross: type: number format: decimal description: The total gross earnings to date example: 25000 tax: type: number format: decimal description: The total tax paid to date example: 5000 taxable: type: number format: decimal description: The total taxable earnings to date example: 24000 ni: type: number format: decimal description: The total National Insurance contributions to date example: 2000 employerNi: type: number format: decimal description: The total employer National Insurance contributions to date example: 2500 employerClass1ANi: type: number format: decimal description: The total employer Class 1A National Insurance contributions to date example: 2500 studentLoan: type: number format: decimal description: The total student loan repayments to date example: 500 postgraduateLoan: type: number format: decimal description: The total postgraduate loan repayments to date example: 300 net: type: number format: decimal description: The total net earnings to date example: 17200 netDeductions: type: number format: decimal description: Deductions taken from net pay, to date. totalEmployerCost: type: number format: decimal description: The total employer cost to date example: 27500 totalCost: type: number format: decimal description: The total cost to date example: 30000 grossForEmployeeNi: type: number format: decimal description: The gross earnings for employee NI calculations to date example: 25000 grossForEmployerNi: type: number format: decimal description: The gross earnings for employer NI calculations to date example: 25000 grossForEmployerClass1ANi: type: number format: decimal description: The gross earnings for employer Class 1A NI calculations to date example: 25000 pension: type: number format: decimal description: >- Deprecated as input: the employee's total pension contributions to date. Send 'pensionContributionsByType' instead (employee contributions broken down by pension scheme type) so FPS YTD reporting can split NetPayArrangement vs ReliefAtSource correctly. On responses, this field is always populated as the sum of 'pensionContributionsByType' for client convenience. Will be removed from input in a future version. example: 500 deprecated: true employerPension: type: number format: decimal description: The employer pension contributions to date example: 375 grossPensionable: type: number format: decimal description: The gross pensionable earnings to date example: 25000 qualifyingEarningsForPension: type: number format: decimal description: Qualifying earnings for pension, to date. statutory: type: object additionalProperties: type: number format: decimal description: >- Dictionary of statutory payment types and amounts. Possible keys: None, StatutorySickPay, StatutoryMaternityPay, StatutoryPaternityPay, StatutoryAdoptionPay, SharedParentalPay, StatutoryParentalBereavementPay, StatutorySharedParentalPay, StatutoryNeoNatalCarePay example: StatutorySickPay: 500 StatutoryMaternityPay: 1000 niBandResult: type: object additionalProperties: $ref: '#/components/schemas/NiCalculationResultDto' description: >- Map of NI category letter (single char) to NI calculation results. Keys must be a single letter (A-Z, case insensitive). Example keys: "A", "B", "C", etc. The band splits (bandResults) in each entry cover the whole employment, both stretches — the same coverage as the per-letter scalar totals (gross, contributions). For directors, the portion of these band splits paid while the director basis applied must also be entered in openingBalanceDirector niBandResult[letter].bandResults as a subset of this map, so the annualised calculation can supersede exactly that portion. pensionContributionsByType: type: object additionalProperties: type: number format: decimal description: >- Employee pension contributions broken down by pension scheme type. This represents the employee's contributions only, as employer contributions are tracked separately via 'employerPension' and are not part of this breakdown. Allowed keys: NetPayArrangement, ReliefAtSource, SalarySacrifice. Required at migration time so FPS YTD reporting (EmpeePenContribnsPaidYTD for NetPayArrangement, EmpeePenContribnsNotPaidYTD for ReliefAtSource) reflects opening-balance contributions correctly. The aggregate 'pension' field on responses is the sum of these values. example: NetPayArrangement: 300 ReliefAtSource: 200 DirectorEarningsToDateDto: type: object description: >- Director earnings to date. Only contains the fields relevant to the annual NI calculation for directors. Send niBandResult keyed by NI category letter; when present it is authoritative and the deprecated scalar totals are ignored. When absent, the scalar totals are attributed to the employee's latest effective NI letter for the year — a lossy fallback that cannot express a director who paid NI under more than one letter. properties: grossForEmployeeNi: type: number format: decimal description: >- Deprecated as input: send niBandResult instead. Ignored when niBandResult is present. Always populated on responses as the sum across letters. deprecated: true grossForEmployerNi: type: number format: decimal description: >- Deprecated as input: send niBandResult instead. Ignored when niBandResult is present. Always populated on responses as the sum across letters. deprecated: true ni: type: number format: decimal description: >- Deprecated as input: send niBandResult instead. Ignored when niBandResult is present. Always populated on responses as the sum across letters. deprecated: true employerNi: type: number format: decimal description: >- Deprecated as input: send niBandResult instead. Ignored when niBandResult is present. Always populated on responses as the sum across letters. deprecated: true niBandResult: type: object additionalProperties: $ref: '#/components/schemas/DirectorLetterAmountsDto' description: >- Director NI-able gross, contributions, and band splits broken down by NI category letter — the same name and shape as the main opening balance's niBandResult, dedicated here to earnings paid while the director basis applied (from appointment). Earnings paid before the appointment belong in the main opening balance's niBandResult, which is dedicated to earnings assessed as a regular employee. 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 items: $ref: '#/components/schemas/EmployeeSalaryVersionDto' description: Every version, oldest first. inForce: allOf: - $ref: '#/components/schemas/EmployeeSalaryVersionDto' nullable: true description: >- The version in force today; null when every version is still in the future. EmployeeNameDto: type: object required: - firstName - lastName properties: title: type: string nullable: true description: >- The person's title, such as Mr or Ms; optional, and checked against HMRC's title rules when sent. example: Mr firstName: type: string description: >- The first forename, reported to HMRC; 1 to 35 characters starting with a letter, using letters, spaces, hyphens and apostrophes. example: John lastName: type: string description: >- The surname, reported to HMRC; 1 to 35 characters starting with a letter, using letters, spaces, hyphens and apostrophes. example: Smith initials: type: string nullable: true description: The employee's initials. middleName: type: string nullable: true description: >- A second forename; optional, and checked against the same rules as firstName when sent. example: Edward 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 EmployeeNiDto: type: object properties: nationalInsuranceNumber: type: string nullable: true description: The National Insurance number for the employee (optional). example: QQ123456C categoriesPerYear: type: object additionalProperties: type: array items: $ref: '#/components/schemas/EmployeeNiCategoryDto' description: National Insurance categories organized by tax year AddressDto: type: object properties: line1: type: string nullable: true description: >- First line of the address; one of the address lines (line1, line2, county, city), each 1 to 35 characters starting with a letter or number. example: 123 Main Street line2: type: string nullable: true description: >- Second line of the address; one of the address lines (line1, line2, county, city), each 1 to 35 characters starting with a letter or number. example: Apt 4B city: type: string nullable: true description: >- Town or city; one of the address lines (line1, line2, county, city), each 1 to 35 characters starting with a letter or number. example: London county: type: string nullable: true description: >- County; one of the address lines (line1, line2, county, city), each 1 to 35 characters starting with a letter or number. example: Greater London postcode: type: string nullable: true description: >- Postcode; checked against HMRC's UK postcode format when countryCode is GB or blank. example: SW1A 1AA countryCode: type: string nullable: true description: >- ISO 3166-1 alpha-2 country code. Defaults to "GB" when omitted or blank. example: GB BankAccountDto: type: object required: - accountNumber - sortCode properties: accountNumber: type: string description: >- UK bank account number. Must be 6-8 digits (zero-padded to 8 for BACS). example: '12345678' sortCode: type: string description: >- UK bank sort code. Must be 6 digits. Hyphens are stripped before validation. example: '123456' accountHolderName: type: string description: >- Name of the account holder. Optional — falls back to employee name for payment files. example: John Smith isPrimaryPayrollAccount: type: boolean description: At least one bank account must be set as primary. example: true allocationPercentage: type: integer format: int32 description: >- Percentage of salary allocated to this account. All accounts must total 100%. example: 100 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' TagDto: type: object properties: name: type: string description: The tag's name within its group. example: FullTime group: type: string description: The group the tag belongs to. example: EmploymentType value: type: string description: The tag's value for that name. example: FullTime PreviousEmploymentEarningsDto: type: object description: >- Earnings from a previous employer in the same tax year (P45 previous employment). Only grossTaxable and tax are needed for cumulative tax calculations. properties: grossTaxable: type: number format: decimal description: Taxable gross earnings from the previous employer (P45 taxable pay). example: 15000 tax: type: number format: decimal description: Tax paid at the previous employer (P45 tax paid). example: 3000 EmployeeDirectorDetailsDto: type: object properties: directorsNICType: type: string enum: - Annual - Alternative 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' EmployeeWorkplaceDetailsDto: type: object properties: workplacePostcode: type: string nullable: true description: The postcode of the workplace this employee reports to. example: E1 6AN WorkingDaysConfigurationDto: type: object description: Configuration of employee's working days properties: standardWorkingDays: $ref: '#/components/schemas/StandardWorkingDaysDto' nullable: true description: Standard working days configuration example: monday: true tuesday: true wednesday: true thursday: true friday: true saturday: false sunday: false shiftPattern: $ref: '#/components/schemas/ShiftPatternDto' nullable: true description: Shift pattern configuration (if applicable) example: rotationStartDate: '2024-01-01' shifts: - name: Morning Shift workingDays: monday: true tuesday: true wednesday: true thursday: true friday: true saturday: false sunday: false durationInDays: 5 - name: Night Shift workingDays: monday: true tuesday: true wednesday: true thursday: true friday: true saturday: false sunday: false durationInDays: 5 patternType: FourOnFourOff workingPattern: type: string enum: - Standard - Shift - Explicit description: Type of working pattern example: Standard explicitSchedule: $ref: '#/components/schemas/ExplicitScheduleDto' nullable: true description: >- Explicit week-by-week schedule, used when workingPattern is "Explicit" EmployeePartnerDetailsDto: type: object properties: nationalInsuranceNumber: type: string nullable: true description: >- The partner's National Insurance number; optional, and checked against the NI number format when sent. example: QQ654321A name: $ref: '#/components/schemas/EmployeeNameDto' description: >- The partner's name, reported to HMRC on the FPS with the first payment of Shared Parental Pay. EmployeeSecondedDetailsDto: type: object properties: stayStatus: type: string enum: - Stay183DaysOrMore - StayLessThan183Days - InOutUK 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 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 DirectorLetterAmountsDto: type: object description: >- Director NI-able earnings, contributions, and band splits accrued under a single NI category letter while the director basis applied. properties: grossForEmployeeNi: type: number format: decimal description: Gross earnings for employee NI accrued under this letter grossForEmployerNi: type: number format: decimal description: Gross earnings for employer NI accrued under this letter employeeNi: type: number format: decimal description: Employee NI already paid under this letter employerNi: type: number format: decimal description: Employer NI already paid under this letter bandResults: type: object additionalProperties: $ref: '#/components/schemas/NiBandResultDto' description: >- NI band splits for earnings paid under this letter while the director basis applied — a subset of the main opening balance's niBandResult band splits, which cover the whole employment. This mirrors the per-letter scalar totals: the main opening balance carries the whole-employment figures, this entry carries the director portion, and for a director for the whole year the two are the same values. Populate for the Alternative method: at the annual reassessment the director portion of the accumulated band splits is superseded by the recomputed annual-basis split, and this subset identifies that portion. For the Annual method the values are stored as a record of what was previously reported, but the annualised calculation and FPS reporting re-derive the band split from cumulative gross and ignore what is entered here. Keys are NI band names matching the main opening balance's band split keys. EmployeeSalaryVersionDto: type: object description: An effective-dated salary version with audit metadata. required: - effectiveFrom - annualSalary - createdDate - createdBy - updatedDate - updatedBy properties: effectiveFrom: type: string format: date description: The date this salary takes effect (YYYY-MM-DD). 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 description: The note given when the salary was set, if any. example: Annual review createdDate: type: string description: When this version was first saved, as a UTC date and time. createdBy: type: string description: The user who first saved this version. updatedDate: type: string description: When this version was last saved, as a UTC date and time. updatedBy: type: string description: The user who last saved this version. contractedHoursPerWeek: type: number format: decimal nullable: true description: >- The hours a week the employee is contracted to work at this salary; null when none were stated. example: 37.5 EmployeeNiCategoryDto: type: object required: - category properties: category: type: string enum: - A - B - C - D - E - F - H - I - J - K - L - M - 'N' - S - V - X - Z description: HMRC-published NI category letter for payroll submissions. example: A effectiveDate: type: string format: date description: Date when this category becomes effective example: '2025-04-06' reason: type: string description: Reason for the category example: HMRC Update issuedBy: type: string description: 'Who issued the category. Valid values: ''HMRC'', ''Employer''' example: HMRC EmployeeStudentLoanDetailsDto: type: object description: The details of the student loan properties: loanType: type: string enum: - Plan1 - Plan2 - Plan4 - Plan5 description: Type of student loan 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 enum: - PostgraduateLoan description: Type of postgraduate loan 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' StandardWorkingDaysDto: type: object description: Standard working days configuration properties: monday: type: boolean description: Whether Monday is a working day example: true tuesday: type: boolean description: Whether Tuesday is a working day example: true wednesday: type: boolean description: Whether Wednesday is a working day example: true thursday: type: boolean description: Whether Thursday is a working day example: true friday: type: boolean description: Whether Friday is a working day example: true saturday: type: boolean description: Whether Saturday is a working day example: false sunday: type: boolean description: Whether Sunday is a working day example: false ShiftPatternDto: type: object description: >- A repeating shift rotation. "Custom" spells the rotation out as an ordered list of shifts: starting on rotationStartDate, each shift runs for its durationInDays and the list then repeats from the top, so the cycle length is the sum of the durations. Every other patternType is a named rotation whose shape is built in, and ignores shifts. required: - rotationStartDate - shifts properties: rotationStartDate: type: string format: date description: The date when the shift pattern rotation begins example: '2024-01-01' shifts: type: array items: $ref: '#/components/schemas/ShiftDto' description: >- The shifts making up one cycle, in the order they are worked. Only read when patternType is "Custom". example: - name: Morning Shift workingDays: monday: true tuesday: true wednesday: true thursday: true friday: true saturday: false sunday: false durationInDays: 5 - name: Night Shift workingDays: monday: true tuesday: true wednesday: true thursday: true friday: true saturday: false sunday: false durationInDays: 5 patternType: type: string enum: - Custom - FourFourFive - FourOnFourOff - ThreeOnThreeOff - TwoOnTwoOff - FiveOnTwoOff description: Type of shift pattern example: FourOnFourOff ExplicitScheduleDto: type: object description: >- An explicit, week-by-week schedule for irregular workers whose pattern does not repeat. required: - weeks properties: weeks: type: array items: $ref: '#/components/schemas/ScheduledWeekDto' description: The scheduled weeks. A week that is not listed counts as not worked. 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 ShiftDto: type: object description: >- One shift within a rotation: the days worked, and how long the shift lasts before the rotation moves on to the next entry in the list. required: - name - workingDays properties: name: type: string description: Name of the shift example: Morning Shift workingDays: $ref: '#/components/schemas/StandardWorkingDaysDto' description: Working days configuration for this shift durationInDays: type: integer format: int32 description: >- How many days this shift lasts before the next one starts. Use 7 for a shift covering a whole week. example: 5 ScheduledWeekDto: type: object description: The working days for a single calendar week within an explicit schedule. required: - weekCommencing - workingDays properties: weekCommencing: type: string description: >- The date this week starts on (any weekday; a 7-day block). Format YYYY-MM-DD. example: '2026-07-06' workingDays: $ref: '#/components/schemas/StandardWorkingDaysDto' description: Which days of that week are worked. 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.