> ## 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. # Update the starter details for a specific employee ## OpenAPI ````yaml /api-reference/specs/pay-api.yaml put /employees/{employeeId}/starter 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: /employees/{employeeId}/starter: put: tags: - Starters & leavers summary: Update the starter details for a specific employee operationId: UpdateStarterDetails parameters: - name: employeeId in: path required: true schema: type: string description: The ID of the employee whose starter details are to be updated requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EmployeeStarterDetailsDto' responses: '200': description: Employee starter details were successfully updated content: application/json: schema: type: object allOf: - $ref: '#/components/schemas/ResponseBody' - properties: content: type: object properties: data: $ref: '#/components/schemas/EmployeeDto' '400': description: >- Invalid request body or employee starter details have already been submitted to HMRC FPS content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '404': description: Employee not found content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '500': description: An internal server error occurred content: application/json: schema: $ref: '#/components/schemas/ResponseBody' components: schemas: 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 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 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 payrollConfigId: type: string description: The payroll config the employee is assigned to. example: payroll_config_001 starterDetails: $ref: '#/components/schemas/EmployeeStarterDetailsDto' leaverDetails: $ref: '#/components/schemas/EmployeeLeaverDetailsDto' earningsToDatePerYear: type: object readOnly: true description: >- Computed year-to-date earnings (opening balance + accumulated payslips). Read-only. additionalProperties: $ref: '#/components/schemas/EmployeeEarningsToDateDto' openingBalance: type: object readOnly: true description: >- Opening balance for this employment. Updated via PUT /employees/{id}/opening-balance. additionalProperties: $ref: '#/components/schemas/EmployeeEarningsToDateDto' openingBalanceDirector: type: object readOnly: true description: >- Opening balance for director earnings. Updated via PUT /employees/{id}/opening-balance. Only NI-relevant fields. additionalProperties: $ref: '#/components/schemas/DirectorEarningsToDateDto' directorEarningsToDatePerYear: type: object readOnly: true description: >- Computed year-to-date director earnings for NI calculation (opening balance + accumulated payslips). Read-only. additionalProperties: $ref: '#/components/schemas/DirectorEarningsToDateDto' payrollId: type: string nullable: true readOnly: true description: >- Payroll ID used as the payId field in HMRC FPS submissions. Updated via PUT /employees/{id}/payroll-id. example: PAY123 createdDate: type: string format: date-time example: '2023-01-15T10:00:00Z' createdBy: type: string example: admin@company.com updatedDate: type: string format: date-time example: '2023-06-01T12:00:00Z' updatedBy: type: string example: hr@company.com 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 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' UpdatableEmployeeDto: type: object required: - name - email - birthGender - birthDate - hoursWorkedCategory properties: name: $ref: '#/components/schemas/EmployeeNameDto' email: type: string format: email 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' description: National Insurance details for the employee birthGender: type: string enum: - Male - Female example: Male phone: type: string nullable: true example: '+447700900123' birthDate: type: string format: date example: '1985-07-23' maritalStatus: type: string nullable: true enum: - Single - Married - Divorced - Widowed - CivilPartnership - FormerCivilPartnership - SurvivorCivilPartnership example: Married hoursWorkedCategory: type: string enum: - UpTo16Hours - From16To24Hours - From24To30Hours - Above30Hours - Other example: Above30Hours salary: type: number format: decimal example: 35000 employeeCode: type: string nullable: true description: Employee code. An optional identifier for the employee. example: EMP001 secondaryEmail: type: string format: email nullable: true example: john.secondary@company.com address: $ref: '#/components/schemas/AddressDto' bankAccounts: type: array items: $ref: '#/components/schemas/BankAccountDto' studentDetails: $ref: '#/components/schemas/EmployeeStudentDetailsDto' tags: type: array items: $ref: '#/components/schemas/TagDto' previousEmployment: type: object description: >- Earnings from a previous employer in the same tax year. Used for cumulative tax calculations only. Does not affect FPS reporting. additionalProperties: $ref: '#/components/schemas/PreviousEmploymentEarningsDto' example: '2026': grossTaxable: 15000 tax: 3000 gender: type: string nullable: true example: Male secondaryPhone: type: string nullable: true example: '+447700900124' passportNumber: type: string nullable: true example: '123456789' previousNames: type: array items: type: string example: - John Doe directorDetails: $ref: '#/components/schemas/EmployeeDirectorDetailsDto' isIrregularEmployment: type: boolean nullable: true example: false isOffPayrollWorker: type: boolean nullable: true example: false workplaceDetails: $ref: '#/components/schemas/EmployeeWorkplaceDetailsDto' workingDays: $ref: '#/components/schemas/WorkingDaysConfigurationDto' partnerDetails: $ref: '#/components/schemas/EmployeePartnerDetailsDto' department: type: string nullable: true example: Engineering jobTitle: type: string nullable: true example: Software Engineer 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 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 default: 0 ni: type: number format: decimal description: The total National Insurance contributions to date example: 2000 default: 0 employerNi: type: number format: decimal description: The total employer National Insurance contributions to date example: 2500 default: 0 employerClass1ANi: type: number format: decimal description: The total employer Class 1A National Insurance contributions to date example: 2500 default: 0 studentLoan: type: number format: decimal description: The total student loan repayments to date example: 500 default: 0 postgraduateLoan: type: number format: decimal description: The total postgraduate loan repayments to date example: 300 default: 0 net: type: number format: decimal description: The total net earnings to date example: 17200 default: 0 totalEmployerCost: type: number format: decimal description: The total employer cost to date example: 27500 default: 0 totalCost: type: number format: decimal description: The total cost to date example: 30000 default: 0 grossForEmployeeNi: type: number format: decimal description: The gross earnings for employee NI calculations to date example: 25000 default: 0 grossForEmployerNi: type: number format: decimal description: The gross earnings for employer NI calculations to date example: 25000 default: 0 grossForEmployerClass1ANi: type: number format: decimal description: The gross earnings for employer Class 1A NI calculations to date example: 25000 default: 0 pension: type: number format: decimal deprecated: true 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 default: 0 employerPension: type: number format: decimal description: The employer pension contributions to date example: 375 default: 0 grossPensionable: type: number format: decimal description: The gross pensionable earnings to date example: 25000 default: 0 statutory: type: object description: > Dictionary of statutory payment types and amounts. Possible keys: None, StatutorySickPay, StatutoryMaternityPay, StatutoryPaternityPay, StatutoryAdoptionPay, SharedParentalPay, StatutoryParentalBereavementPay, StatutorySharedParentalPay, StatutoryNeoNatalCarePay additionalProperties: type: number format: decimal example: StatutorySickPay: 500 StatutoryMaternityPay: 1000 niBandResult: 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 are dedicated to earnings assessed as a regular employee: for directors they must cover only earnings paid before the appointment. Band splits for earnings paid while the director basis applied have a dedicated home in openingBalanceDirector niBandResult[letter].bandResults. The per-letter scalar totals (gross, contributions) still cover the whole employment, both stretches. type: object nullable: true additionalProperties: $ref: '#/components/schemas/NiCalculationResultDto' pensionContributionsByType: type: object nullable: true description: > Employee pension contributions broken down by pension scheme type. This represents the employee's contributions only — 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. additionalProperties: type: number format: decimal 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 default: 0 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 default: 0 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 default: 0 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 default: 0 niBandResult: type: object 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. additionalProperties: $ref: '#/components/schemas/DirectorLetterAmountsDto' 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 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 required: - categoriesPerYear 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 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 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 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 required: - name - group - value properties: name: type: string example: FullTime group: type: string example: EmploymentType value: type: string 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 default: 0 tax: type: number format: decimal description: Tax paid at the previous employer (P45 tax paid). example: 3000 default: 0 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' EmployeeWorkplaceDetailsDto: type: object properties: workplaceId: type: string example: workplace_001 workplaceName: type: string example: Head Office address: $ref: '#/components/schemas/AddressDto' WorkingDaysConfigurationDto: type: object description: Configuration of employee's working days properties: standardWorkingDays: $ref: '#/components/schemas/StandardWorkingDaysDto' 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' 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 weekNumber: 1 - name: Night Shift workingDays: monday: true tuesday: true wednesday: true thursday: true friday: true saturday: false sunday: false durationInDays: 5 weekNumber: 2 patternType: FourOnFourOff patternWeeks: 8 workingPattern: type: string description: Type of working pattern enum: - Standard - Shift - Explicit default: Standard example: Standard explicitSchedule: $ref: '#/components/schemas/ExplicitScheduleDto' description: >- Explicit week-by-week schedule, used when workingPattern is "Explicit" EmployeePartnerDetailsDto: type: object properties: name: $ref: '#/components/schemas/EmployeeNameDto' nationalInsuranceNumber: type: string nullable: true example: QQ654321A 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 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 default: 0 grossForEmployerNi: type: number format: decimal description: Gross earnings for employer NI accrued under this letter default: 0 employeeNi: type: number format: decimal description: Employee NI already paid under this letter default: 0 employerNi: type: number format: decimal description: Employer NI already paid under this letter default: 0 bandResults: type: object nullable: true description: >- NI band splits for earnings paid under this letter while the director basis applied — the dedicated home for director band splits (the main opening balance's niBandResult band splits are dedicated to earnings assessed as a regular employee, before the appointment). Populate for the Alternative method, where the director stretch is assessed per period and these values feed FPS YTD band reporting additively. 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. additionalProperties: $ref: '#/components/schemas/NiBandResultDto' EmployeeNiCategoryDto: type: object required: - category - effectiveDate - reason - issuedBy properties: category: type: string description: HMRC-published NI category letter for payroll submissions. example: A enum: - A - B - C - D - E - F - H - I - J - K - L - M - 'N' - S - V - X - Z 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 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' 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: Configuration for shift-based working patterns 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 description: List of shifts in the pattern items: $ref: '#/components/schemas/ShiftDto' example: - name: Morning Shift workingDays: monday: true tuesday: true wednesday: true thursday: true friday: true saturday: false sunday: false durationInDays: 5 weekNumber: 1 - name: Night Shift workingDays: monday: true tuesday: true wednesday: true thursday: true friday: true saturday: false sunday: false durationInDays: 5 weekNumber: 2 patternType: type: string description: Type of shift pattern enum: - Custom - FourFourFive - FourOnFourOff - ThreeOnThreeOff - TwoOnTwoOff - FiveOnTwoOff default: Custom example: FourOnFourOff patternWeeks: type: integer description: Number of weeks the rota repeats over (1 to 53) default: 1 example: 8 ExplicitScheduleDto: type: object description: >- An explicit, week-by-week schedule for irregular workers whose pattern does not repeat. properties: weeks: type: array items: $ref: '#/components/schemas/ScheduledWeekDto' 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: Configuration for a single shift in a shift pattern 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 description: Number of days this shift lasts default: 1 example: 5 weekNumber: type: integer description: Week number in the pattern when this shift occurs default: 1 example: 1 ScheduledWeekDto: type: object description: The working days for a single calendar week within an explicit schedule. 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' 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). ````