> ## Documentation Index > Fetch the complete documentation index at: https://docs.intermezzo.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Employee ## OpenAPI ````yaml /api-reference/preview.json post /gb/organizations/{organization_id}/employees openapi: 3.2.0 info: title: Intermezzo Global Payroll summary: Global Payroll Platform description: Intermezzo's global payroll apis, organized by country version: '2026-10-07' x-logo: url: /static/icon.svg servers: - url: https://preview.intermezzo.ai description: Preview security: [] paths: /gb/organizations/{organization_id}/employees: post: tags: - Great Britain - Employees summary: Create Employee operationId: gb_employee_create parameters: - name: organization_id in: path required: true schema: type: string title: Organization Id - name: X-Acting-User in: header required: false schema: anyOf: - type: string minLength: 1 maxLength: 255 - type: 'null' description: >- The person acting through the access credential, recorded as `created_by` of what the request writes. Audit only: access is checked on the credential. title: X-Acting-User description: >- The person acting through the access credential, recorded as `created_by` of what the request writes. Audit only: access is checked on the credential. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GBEmployeeCreateRequest' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/GBEmployeeResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - BearerToken: [] components: schemas: GBEmployeeCreateRequest: properties: external_ref: type: string maxLength: 255 minLength: 1 title: External Ref description: >- The integrator's own stable key, unique within the organization. Generated when absent. valid_from: type: string format: date title: Valid From description: The date every satellite starts on core: anyOf: - $ref: '#/components/schemas/GBEmployeeCore' - type: 'null' address: anyOf: - $ref: '#/components/schemas/GBEmployeeAddress' - type: 'null' job: anyOf: - $ref: '#/components/schemas/GBEmployeeJob' - type: 'null' tax: anyOf: - $ref: '#/components/schemas/GBEmployeeTax' - type: 'null' insurance: anyOf: - $ref: '#/components/schemas/GBEmployeeInsurance' - type: 'null' compensation: anyOf: - $ref: '#/components/schemas/GBEmployeeCompensation' - type: 'null' bank: anyOf: - $ref: '#/components/schemas/GBEmployeeBank' - type: 'null' additionalProperties: false type: object required: - valid_from title: GBEmployeeCreateRequest description: >- Creating an employee: the hub, `valid_from`, and the satellites sent. Each satellite starts on `[valid_from, 9999-12-31)`; one not sent starts at its schema defaults. GBEmployeeResponse: properties: id: type: string title: Id external_ref: anyOf: - type: string - type: 'null' title: External Ref created_at: type: string format: date-time title: Created At readOnly: true created_by: type: string title: Created By description: >- Who created the hub: the acting user (`X-Acting-User`, else the access credential), `system` for our own writes, or `:` for a write on an authority's behalf, e.g. `hmrc:P6`. readOnly: true deleted_at: anyOf: - type: string format: date-time - type: 'null' title: Deleted At description: When the hub was closed readOnly: true organization_id: type: string title: Organization Id core: anyOf: - $ref: '#/components/schemas/GBEmployeeCoreSatellite' - type: 'null' address: anyOf: - $ref: '#/components/schemas/GBEmployeeAddressSatellite' - type: 'null' job: anyOf: - $ref: '#/components/schemas/GBEmployeeJobSatellite' - type: 'null' tax: anyOf: - $ref: '#/components/schemas/GBEmployeeTaxSatellite' - type: 'null' insurance: anyOf: - $ref: '#/components/schemas/GBEmployeeInsuranceSatellite' - type: 'null' compensation: anyOf: - $ref: '#/components/schemas/GBEmployeeCompensationSatellite' - type: 'null' bank: anyOf: - $ref: '#/components/schemas/GBEmployeeBankSatellite' - type: 'null' status: $ref: '#/components/schemas/GBEmployeeStatus' additionalProperties: false type: object required: - id - external_ref - created_at - created_by - deleted_at - organization_id - status title: GBEmployeeResponse description: >- The employee with every satellite as it reads on one date. A satellite with no slice on an explicit date is absent. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError GBEmployeeCore: properties: employee_name: type: string title: Employee Name description: Employee name examples: - John Smith gender: anyOf: - $ref: '#/components/schemas/GBGender' - type: 'null' description: Gender marital_status: anyOf: - $ref: '#/components/schemas/MaritalStatus' - type: 'null' description: Marital status birth_date: anyOf: - type: string format: date - type: 'null' title: Birth Date description: Birth date personal_email: anyOf: - type: string format: email - type: 'null' title: Personal Email work_email: anyOf: - type: string format: email - type: 'null' title: Work Email phone_numbers: items: $ref: '#/components/schemas/Phones' type: array title: Phone Numbers additionalProperties: false type: object required: - employee_name title: GBEmployeeCore description: Identity of the person, as payroll and filing need it. GBEmployeeAddress: properties: address: type: string minLength: 1 title: Address description: >- The address as one string, lines separated by commas or new lines. FPS files the first four lines. examples: - 10 Downing Street, London, SW1A 2AA additionalProperties: false type: object required: - address title: GBEmployeeAddress description: The person's residence address, as filed to HMRC. GBEmployeeJob: properties: start_date: anyOf: - type: string format: date - type: 'null' title: Start Date description: Employment start date contracted_weekly_hours: anyOf: - type: integer - type: 'null' title: Contracted Weekly Hours description: Contracted weekly hours default: 40 department: anyOf: - type: string - type: 'null' title: Department description: Department contracted_weekdays: anyOf: - items: $ref: '#/components/schemas/Weekday' type: array maxItems: 7 minItems: 1 - type: 'null' title: Contracted Weekdays description: Contracted working days of the week worker_type: $ref: '#/components/schemas/WorkerType' description: UK employment status (employee, worker, director) default: EMPLOYEE director_since: anyOf: - type: string format: date - type: 'null' title: Director Since description: Date appointed as director (None if not a director) pay_basis: $ref: '#/components/schemas/PayBasis' description: How pay and hours are determined default: SALARIED apprenticeship: anyOf: - $ref: '#/components/schemas/Apprenticeship' - type: 'null' description: Apprenticeship details (None = not an apprentice) p45_issued: type: boolean title: P45 Issued description: >- True once a P45 has been issued for this employment (post-cessation). Drives the weekly NIC earnings period for post-P45 payments. Distinct from the inbound-starter p45_gross_pay/p45_tax_amount in tax, which carry a new joiner's prior-employer figures. default: false irregular_payment_pattern: type: boolean title: Irregular Payment Pattern description: >- The employee is not paid every pay period (casual, seasonal, annual director pay). Reported to HMRC as IrrEmp so the employment is not treated as ceased after a run of periods without payment. default: false ordinarily_works_in_uk: type: boolean title: Ordinarily Works In Uk description: >- Whether the worker's ordinary place of work under their contract is in the UK (per TPR Detailed Guidance No. 1). If False, the employer has no statutory auto-enrolment duties for this worker. Employees on temporary overseas secondment who remain on UK payroll and whose ordinary place of work is the UK stay True: this flag reflects the contractual base, not the employee's current physical location. default: true proration_basis: anyOf: - $ref: '#/components/schemas/ProrationBasis-Input' - type: 'null' description: Employee-level override of the inherited proration basis additionalProperties: false type: object title: GBEmployeeJob description: The terms of the employment as a client writes them. GBEmployeeTax: properties: rti_id: anyOf: - type: string maxLength: 35 minLength: 1 - type: 'null' title: Rti Id description: >- RTI Payroll ID, unique for this employee in HMRC submissions. Generated when absent. tax_code: type: string description: HMRC tax code (e.g. '1257L', 'K475', 'BR') examples: - 1257L student_loan_type: anyOf: - $ref: '#/components/schemas/StudentLoanPlanType' - type: 'null' description: Student loan type postgraduate_loan: type: boolean title: Postgraduate Loan description: Postgraduate loan? default: false p45_gross_pay: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: P45 Gross Pay description: P45 gross pay default: '0.00' p45_tax_amount: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: P45 Tax Amount description: P45 tax amount default: '0.00' additionalProperties: false type: object required: - tax_code title: GBEmployeeTax GBEmployeeInsurance: properties: national_insurance_number: anyOf: - type: string maxLength: 9 minLength: 9 - type: 'null' title: National Insurance Number description: National Insurance number nic_category: $ref: '#/components/schemas/NICCategory' description: NIC category letter additionalProperties: false type: object required: - nic_category title: GBEmployeeInsurance GBEmployeeCompensation: properties: pay_group_id: anyOf: - type: string - type: 'null' title: Pay Group Id description: The pay group the employee is paid in earnings: anyOf: - items: $ref: '#/components/schemas/AmountEarnings-Input' type: array - type: 'null' title: Earnings benefits: anyOf: - items: $ref: '#/components/schemas/Benefits-Input' type: array - type: 'null' title: Benefits deductions: anyOf: - items: $ref: '#/components/schemas/Deductions-Input' type: array - type: 'null' title: Deductions reimbursements: anyOf: - items: $ref: '#/components/schemas/Reimbursement-Input' type: array - type: 'null' title: Reimbursements additionalProperties: false type: object title: GBEmployeeCompensation description: >- Standing pay elements and the pay group they are paid in (PDR-0007, PDR-0012). GBEmployeeBank: properties: accounts: items: $ref: '#/components/schemas/GBBankAccount' type: array title: Accounts additionalProperties: false type: object title: GBEmployeeBank GBEmployeeCoreSatellite: properties: employee_name: anyOf: - type: string - type: 'null' title: Employee Name description: Employee name gender: anyOf: - $ref: '#/components/schemas/GBGender' - type: 'null' description: Gender marital_status: anyOf: - $ref: '#/components/schemas/MaritalStatus' - type: 'null' description: Marital status birth_date: anyOf: - type: string format: date - type: 'null' title: Birth Date description: Birth date personal_email: anyOf: - type: string format: email - type: 'null' title: Personal Email work_email: anyOf: - type: string format: email - type: 'null' title: Work Email phone_numbers: items: $ref: '#/components/schemas/Phones' type: array title: Phone Numbers edition: type: integer title: Edition readOnly: true valid_from: type: string format: date title: Valid From valid_to: type: string format: date title: Valid To created_at: type: string format: date-time title: Created At readOnly: true created_by: type: string title: Created By description: >- Who wrote the edition: the acting user (`X-Acting-User`, else the access credential), `system` for our own writes, or `:` for a write on an authority's behalf, e.g. `hmrc:P6`. readOnly: true additionalProperties: false type: object required: - edition - valid_from - valid_to - created_at - created_by title: GBEmployeeCoreSatellite GBEmployeeAddressSatellite: properties: address: anyOf: - type: string - type: 'null' title: Address edition: type: integer title: Edition readOnly: true valid_from: type: string format: date title: Valid From valid_to: type: string format: date title: Valid To created_at: type: string format: date-time title: Created At readOnly: true created_by: type: string title: Created By description: >- Who wrote the edition: the acting user (`X-Acting-User`, else the access credential), `system` for our own writes, or `:` for a write on an authority's behalf, e.g. `hmrc:P6`. readOnly: true additionalProperties: false type: object required: - edition - valid_from - valid_to - created_at - created_by title: GBEmployeeAddressSatellite GBEmployeeJobSatellite: properties: start_date: anyOf: - type: string format: date - type: 'null' title: Start Date description: Employment start date contracted_weekly_hours: anyOf: - type: integer - type: 'null' title: Contracted Weekly Hours description: Contracted weekly hours default: 40 department: anyOf: - type: string - type: 'null' title: Department description: Department contracted_weekdays: anyOf: - items: $ref: '#/components/schemas/Weekday' type: array maxItems: 7 minItems: 1 - type: 'null' title: Contracted Weekdays description: Contracted working days of the week worker_type: $ref: '#/components/schemas/WorkerType' description: UK employment status (employee, worker, director) default: EMPLOYEE director_since: anyOf: - type: string format: date - type: 'null' title: Director Since description: Date appointed as director (None if not a director) pay_basis: $ref: '#/components/schemas/PayBasis' description: How pay and hours are determined default: SALARIED apprenticeship: anyOf: - $ref: '#/components/schemas/Apprenticeship' - type: 'null' description: Apprenticeship details (None = not an apprentice) p45_issued: type: boolean title: P45 Issued description: >- True once a P45 has been issued for this employment (post-cessation). Drives the weekly NIC earnings period for post-P45 payments. Distinct from the inbound-starter p45_gross_pay/p45_tax_amount in tax, which carry a new joiner's prior-employer figures. default: false irregular_payment_pattern: type: boolean title: Irregular Payment Pattern description: >- The employee is not paid every pay period (casual, seasonal, annual director pay). Reported to HMRC as IrrEmp so the employment is not treated as ceased after a run of periods without payment. default: false ordinarily_works_in_uk: type: boolean title: Ordinarily Works In Uk description: >- Whether the worker's ordinary place of work under their contract is in the UK (per TPR Detailed Guidance No. 1). If False, the employer has no statutory auto-enrolment duties for this worker. Employees on temporary overseas secondment who remain on UK payroll and whose ordinary place of work is the UK stay True: this flag reflects the contractual base, not the employee's current physical location. default: true proration_basis: anyOf: - $ref: '#/components/schemas/ProrationBasis-Output' - type: 'null' description: Employee-level override of the inherited proration basis end_date: anyOf: - type: string format: date - type: 'null' title: End Date description: Last day of employment readOnly: true edition: type: integer title: Edition readOnly: true valid_from: type: string format: date title: Valid From valid_to: type: string format: date title: Valid To created_at: type: string format: date-time title: Created At readOnly: true created_by: type: string title: Created By description: >- Who wrote the edition: the acting user (`X-Acting-User`, else the access credential), `system` for our own writes, or `:` for a write on an authority's behalf, e.g. `hmrc:P6`. readOnly: true additionalProperties: false type: object required: - edition - valid_from - valid_to - created_at - created_by title: GBEmployeeJobSatellite GBEmployeeTaxSatellite: properties: rti_id: anyOf: - type: string maxLength: 35 minLength: 1 - type: 'null' title: Rti Id description: >- RTI Payroll ID, unique for this employee in HMRC submissions. Generated when absent. tax_code: anyOf: - type: string - type: 'null' student_loan_type: anyOf: - $ref: '#/components/schemas/StudentLoanPlanType' - type: 'null' description: Student loan type postgraduate_loan: type: boolean title: Postgraduate Loan description: Postgraduate loan? default: false p45_gross_pay: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: P45 Gross Pay description: P45 gross pay default: '0.00' p45_tax_amount: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: P45 Tax Amount description: P45 tax amount default: '0.00' edition: type: integer title: Edition readOnly: true valid_from: type: string format: date title: Valid From valid_to: type: string format: date title: Valid To created_at: type: string format: date-time title: Created At readOnly: true created_by: type: string title: Created By description: >- Who wrote the edition: the acting user (`X-Acting-User`, else the access credential), `system` for our own writes, or `:` for a write on an authority's behalf, e.g. `hmrc:P6`. readOnly: true additionalProperties: false type: object required: - edition - valid_from - valid_to - created_at - created_by title: GBEmployeeTaxSatellite GBEmployeeInsuranceSatellite: properties: national_insurance_number: anyOf: - type: string maxLength: 9 minLength: 9 - type: 'null' title: National Insurance Number description: National Insurance number nic_category: anyOf: - $ref: '#/components/schemas/NICCategory' - type: 'null' edition: type: integer title: Edition readOnly: true valid_from: type: string format: date title: Valid From valid_to: type: string format: date title: Valid To created_at: type: string format: date-time title: Created At readOnly: true created_by: type: string title: Created By description: >- Who wrote the edition: the acting user (`X-Acting-User`, else the access credential), `system` for our own writes, or `:` for a write on an authority's behalf, e.g. `hmrc:P6`. readOnly: true additionalProperties: false type: object required: - edition - valid_from - valid_to - created_at - created_by title: GBEmployeeInsuranceSatellite GBEmployeeCompensationSatellite: properties: pay_group_id: anyOf: - type: string - type: 'null' title: Pay Group Id description: The pay group the employee is paid in earnings: anyOf: - items: $ref: '#/components/schemas/AmountEarnings-Output' type: array - type: 'null' title: Earnings benefits: anyOf: - items: $ref: '#/components/schemas/Benefits-Output' type: array - type: 'null' title: Benefits deductions: anyOf: - items: $ref: '#/components/schemas/Deductions-Output' type: array - type: 'null' title: Deductions reimbursements: anyOf: - items: $ref: '#/components/schemas/Reimbursement-Output' type: array - type: 'null' title: Reimbursements edition: type: integer title: Edition readOnly: true valid_from: type: string format: date title: Valid From valid_to: type: string format: date title: Valid To created_at: type: string format: date-time title: Created At readOnly: true created_by: type: string title: Created By description: >- Who wrote the edition: the acting user (`X-Acting-User`, else the access credential), `system` for our own writes, or `:` for a write on an authority's behalf, e.g. `hmrc:P6`. readOnly: true additionalProperties: false type: object required: - edition - valid_from - valid_to - created_at - created_by title: GBEmployeeCompensationSatellite GBEmployeeBankSatellite: properties: accounts: items: $ref: '#/components/schemas/GBBankAccountRead' type: array title: Accounts edition: type: integer title: Edition readOnly: true valid_from: type: string format: date title: Valid From valid_to: type: string format: date title: Valid To created_at: type: string format: date-time title: Created At readOnly: true created_by: type: string title: Created By description: >- Who wrote the edition: the acting user (`X-Acting-User`, else the access credential), `system` for our own writes, or `:` for a write on an authority's behalf, e.g. `hmrc:P6`. readOnly: true additionalProperties: false type: object required: - edition - valid_from - valid_to - created_at - created_by title: GBEmployeeBankSatellite GBEmployeeStatus: properties: {} additionalProperties: false type: object title: GBEmployeeStatus description: >- The read-only status satellite. It carries no fields; it exists so that every employee read has a `status` object. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError GBGender: type: string enum: - M - F title: GBGender description: Legally recognized genders in the UK. MaritalStatus: type: string enum: - Single - Married title: MaritalStatus Phones: properties: phone_number: type: string format: phone title: Phone Number phone_type: $ref: '#/components/schemas/payroll__gb__schema__employee__core__PhoneType' is_primary: anyOf: - type: boolean - type: 'null' title: Is Primary description: Is this the primary phone number for the employee? default: false additionalProperties: false type: object required: - phone_number - phone_type title: Phones Weekday: type: string enum: - Monday - Tuesday - Wednesday - Thursday - Friday - Saturday - Sunday title: Weekday description: Days of the week. WorkerType: type: string enum: - EMPLOYEE - DIRECTOR title: WorkerType description: 'UK employment status: employee or company director.' PayBasis: type: string enum: - SALARIED - HOURLY title: PayBasis description: How the worker's pay and hours are determined. Apprenticeship: properties: start_date: type: string format: date title: Start Date description: Start date of current apprenticeship agreement expected_end_date: anyOf: - type: string format: date - type: 'null' title: Expected End Date description: Expected end date (informational) level: type: integer maximum: 7 minimum: 2 title: Level description: UK apprenticeship level (2-7) additionalProperties: false type: object required: - start_date - level title: Apprenticeship description: Apprenticeship details for NMW rate determination. ProrationBasis-Input: properties: mode: $ref: '#/components/schemas/BasisMode' business_days_per_year: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Business Days Per Year type: object required: - mode title: ProrationBasis description: >- Resolved proration basis for an employee-period: the apportionment mode plus, for working-day modes, the annual divisor 'rate' (e.g. 260 / 252). CALENDAR_DAY is the statutory annual/365 calc and carries no rate (business_days_per_year is None). Frozen: a resolved basis is an immutable value. A compute phase that needs a different rate must construct a new instance, never mutate one in place (the same object is shared as ValuationState.basis's default). StudentLoanPlanType: type: string enum: - Plan1 - Plan2 - Plan4 title: StudentLoanPlanType description: Types of student loan plans NICCategory: type: string enum: - A - B - C - D - E - F - H - I - J - K - L - M - 'N' - S - V - X - Z title: NICCategory description: NIC Letter Categories AmountEarnings-Input: properties: external_ref: anyOf: - type: string - type: 'null' title: External Ref description: >- Caller-owned line key, scoped to (payrun, employee, wage_type). Re-send with the same value to patch that line in place. Omit for the single default line of the wage type (also patched in place on re-send). Use distinct values to carry multiple lines of one wage type. earning_type: type: string const: AMOUNT title: Earning Type default: AMOUNT wage_type_code: type: string title: Wage Type Code description: Wage type code from catalog (e.g. UK-E-001) amount: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$ title: Amount description: >- Earnings amount (negative values represent period adjustments, e.g. leave reductions) earning_frequency: anyOf: - $ref: '#/components/schemas/PayCycle' - type: 'null' description: If recurring, specify the frequency default: MONTH is_lumpsum: type: boolean title: Is Lumpsum description: True if onetime. Defaults to False default: false sacrificed_amount: anyOf: - type: number minimum: 0 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$ - type: 'null' title: Sacrificed Amount description: >- Amount of this earning the employee has sacrificed (Type A OpRA). Pre-tax. Must be > 0 when set. Wage type must have is_salary_sacrifice_allowed=True additionalProperties: false type: object required: - wage_type_code - amount title: AmountEarnings description: Fixed-amount earnings (salary, bonus, allowance). Amount + frequency. Benefits-Input: properties: external_ref: anyOf: - type: string - type: 'null' title: External Ref description: >- Caller-owned line key, scoped to (payrun, employee, wage_type). Re-send with the same value to patch that line in place. Omit for the single default line of the wage type (also patched in place on re-send). Use distinct values to carry multiple lines of one wage type. wage_type_code: type: string title: Wage Type Code description: Wage type code from catalog (e.g. UK-B-001) amount: anyOf: - type: number minimum: 0 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$ - type: 'null' title: Amount description: Amount of benefit default: '0.00' make_good_amount: anyOf: - type: number minimum: 0 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$ - type: 'null' title: Make Good Amount description: Amount paid by employee for the benefit default: '0.00' foregone_amount: anyOf: - type: number minimum: 0 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$ - type: 'null' title: Foregone Amount description: If subject to OpRa, amount foregone default: '0.00' cash_alternative_amount: anyOf: - type: number minimum: 0 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$ - type: 'null' title: Cash Alternative Amount description: >- Cash alternative the employee declined in favour of this benefit (Type B OpRA). Contributes to BIK higher-of valuation only; does NOT reduce gross. Requires is_salary_sacrifice_allowed=True on the wage type. default: '0.00' additionalProperties: false type: object required: - wage_type_code title: Benefits Deductions-Input: properties: external_ref: anyOf: - type: string - type: 'null' title: External Ref description: >- Caller-owned line key, scoped to (payrun, employee, wage_type). Re-send with the same value to patch that line in place. Omit for the single default line of the wage type (also patched in place on re-send). Use distinct values to carry multiple lines of one wage type. wage_type_code: type: string title: Wage Type Code description: Wage type code from catalog (e.g. UK-D-001) amount: anyOf: - type: number minimum: 0 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$ title: Amount sacrificed_amount: anyOf: - type: number minimum: 0 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$ - type: 'null' title: Sacrificed Amount description: >- Portion of this deduction that is pre-tax salary sacrifice (Type A OpRA). Must be > 0 and <= amount when set. Wage type must have is_salary_sacrifice_allowed=True (validated at service layer). additionalProperties: false type: object required: - wage_type_code - amount title: Deductions Reimbursement-Input: properties: external_ref: anyOf: - type: string - type: 'null' title: External Ref description: >- Caller-owned line key, scoped to (payrun, employee, wage_type). Re-send with the same value to patch that line in place. Omit for the single default line of the wage type (also patched in place on re-send). Use distinct values to carry multiple lines of one wage type. wage_type_code: type: string title: Wage Type Code description: Wage type code from catalog (e.g. UK-R-001) amount: anyOf: - type: number minimum: 0 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$ title: Amount additionalProperties: false type: object required: - wage_type_code - amount title: Reimbursement GBBankAccount: properties: account_number: type: string pattern: ^\d{8}$ title: Account Number examples: - '31926819' sort_code: type: string pattern: ^\d{6}$ title: Sort Code description: Six digits; dashes and spaces are removed. examples: - '200015' financial_institution_name: anyOf: - type: string - type: 'null' title: Financial Institution Name examples: - Lloyds Bank is_primary: type: boolean title: Is Primary description: Receives the whole net pay when no account has an allocation default: false is_active: type: boolean title: Is Active description: Inactive accounts are not paid into default: true allocation_percentage: anyOf: - type: number maximum: 100 exclusiveMinimum: 0 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Allocation Percentage description: >- Share of net pay paid into this account. Set on every active account that receives a share; the shares sum to 100. additionalProperties: false type: object required: - account_number - sort_code title: GBBankAccount description: A UK account an employee is paid into by BACS. ProrationBasis-Output: properties: mode: $ref: '#/components/schemas/BasisMode' business_days_per_year: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Business Days Per Year type: object required: - mode title: ProrationBasis description: >- Resolved proration basis for an employee-period: the apportionment mode plus, for working-day modes, the annual divisor 'rate' (e.g. 260 / 252). CALENDAR_DAY is the statutory annual/365 calc and carries no rate (business_days_per_year is None). Frozen: a resolved basis is an immutable value. A compute phase that needs a different rate must construct a new instance, never mutate one in place (the same object is shared as ValuationState.basis's default). AmountEarnings-Output: properties: external_ref: anyOf: - type: string - type: 'null' title: External Ref description: >- Caller-owned line key, scoped to (payrun, employee, wage_type). Re-send with the same value to patch that line in place. Omit for the single default line of the wage type (also patched in place on re-send). Use distinct values to carry multiple lines of one wage type. earning_type: type: string const: AMOUNT title: Earning Type default: AMOUNT wage_type_code: type: string title: Wage Type Code description: Wage type code from catalog (e.g. UK-E-001) amount: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$ title: Amount description: >- Earnings amount (negative values represent period adjustments, e.g. leave reductions) earning_frequency: anyOf: - $ref: '#/components/schemas/PayCycle' - type: 'null' description: If recurring, specify the frequency default: MONTH is_lumpsum: type: boolean title: Is Lumpsum description: True if onetime. Defaults to False default: false sacrificed_amount: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$ - type: 'null' title: Sacrificed Amount description: >- Amount of this earning the employee has sacrificed (Type A OpRA). Pre-tax. Must be > 0 when set. Wage type must have is_salary_sacrifice_allowed=True additionalProperties: false type: object required: - wage_type_code - amount title: AmountEarnings description: Fixed-amount earnings (salary, bonus, allowance). Amount + frequency. Benefits-Output: properties: external_ref: anyOf: - type: string - type: 'null' title: External Ref description: >- Caller-owned line key, scoped to (payrun, employee, wage_type). Re-send with the same value to patch that line in place. Omit for the single default line of the wage type (also patched in place on re-send). Use distinct values to carry multiple lines of one wage type. wage_type_code: type: string title: Wage Type Code description: Wage type code from catalog (e.g. UK-B-001) amount: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$ - type: 'null' title: Amount description: Amount of benefit default: '0.00' make_good_amount: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$ - type: 'null' title: Make Good Amount description: Amount paid by employee for the benefit default: '0.00' foregone_amount: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$ - type: 'null' title: Foregone Amount description: If subject to OpRa, amount foregone default: '0.00' cash_alternative_amount: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$ - type: 'null' title: Cash Alternative Amount description: >- Cash alternative the employee declined in favour of this benefit (Type B OpRA). Contributes to BIK higher-of valuation only; does NOT reduce gross. Requires is_salary_sacrifice_allowed=True on the wage type. default: '0.00' additionalProperties: false type: object required: - wage_type_code title: Benefits Deductions-Output: properties: external_ref: anyOf: - type: string - type: 'null' title: External Ref description: >- Caller-owned line key, scoped to (payrun, employee, wage_type). Re-send with the same value to patch that line in place. Omit for the single default line of the wage type (also patched in place on re-send). Use distinct values to carry multiple lines of one wage type. wage_type_code: type: string title: Wage Type Code description: Wage type code from catalog (e.g. UK-D-001) amount: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$ title: Amount sacrificed_amount: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$ - type: 'null' title: Sacrificed Amount description: >- Portion of this deduction that is pre-tax salary sacrifice (Type A OpRA). Must be > 0 and <= amount when set. Wage type must have is_salary_sacrifice_allowed=True (validated at service layer). additionalProperties: false type: object required: - wage_type_code - amount title: Deductions Reimbursement-Output: properties: external_ref: anyOf: - type: string - type: 'null' title: External Ref description: >- Caller-owned line key, scoped to (payrun, employee, wage_type). Re-send with the same value to patch that line in place. Omit for the single default line of the wage type (also patched in place on re-send). Use distinct values to carry multiple lines of one wage type. wage_type_code: type: string title: Wage Type Code description: Wage type code from catalog (e.g. UK-R-001) amount: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$ title: Amount additionalProperties: false type: object required: - wage_type_code - amount title: Reimbursement GBBankAccountRead: properties: account_number: anyOf: - type: string - type: 'null' title: Account Number sort_code: anyOf: - type: string - type: 'null' title: Sort Code financial_institution_name: anyOf: - type: string - type: 'null' title: Financial Institution Name examples: - Lloyds Bank is_primary: type: boolean title: Is Primary description: Receives the whole net pay when no account has an allocation default: false is_active: type: boolean title: Is Active description: Inactive accounts are not paid into default: true allocation_percentage: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Allocation Percentage additionalProperties: false type: object title: GBBankAccountRead description: >- An account as stored. Accounts moved from before the bank satellite were not checked against the UK formats, so a read does not check them either. payroll__gb__schema__employee__core__PhoneType: type: string enum: - mobile - home - work title: PhoneType BasisMode: type: string enum: - CALENDAR_DAY - CONTRACTED_DAY - CONTRACTED_HOURS title: BasisMode description: Salary-apportionment basis for proration. PayCycle: type: string enum: - YEAR - MONTH - WEEK - TWO_WEEK - FOUR_WEEK - QUARTER - BIANNUAL title: PayCycle description: >- Employee pay cadence (WEEK, MONTH, etc.). The `UpperStrEnum` base keeps members equal to their upper-case names, so stored payloads and API strings round-trip. securitySchemes: BearerToken: type: http scheme: bearer bearerFormat: JWT description: Get token from Auth0 and paste it here ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.