> ## 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.

# Run Payroll



## OpenAPI

````yaml /api-reference/preview.json post /gb/organizations/{organization_id}/payrolls
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security: []
paths:
  /gb/organizations/{organization_id}/payrolls:
    post:
      tags:
        - Great Britain
        - Great Britain Payroll Run
      summary: Run Payroll
      operationId: run_payroll_gb_organizations__organization_id__payrolls_post
      parameters:
        - name: organization_id
          in: path
          required: true
          schema:
            anyOf:
              - type: string
              - type: string
                format: uuid
            title: Organization Id
        - name: X-Include-Execution-History
          in: header
          required: false
          schema:
            type: boolean
            default: false
            title: X-Include-Execution-History
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/payroll__gb__schema__request__PayrollRequest
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePayrollTaskResponse_PayrunStatus_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - BearerToken: []
components:
  schemas:
    payroll__gb__schema__request__PayrollRequest:
      properties:
        external_ref:
          anyOf:
            - type: string
            - type: 'null'
          title: External Ref
          description: External reference for payroll run
        payroll_group:
          items:
            $ref: >-
              #/components/schemas/payroll__gb__schema__request__PayrollRequestBase
          type: array
          title: Payroll Group
        pay_group_id:
          anyOf:
            - type: string
            - type: string
              format: uuid
          title: Pay Group Id
        pay_calendar_id:
          anyOf:
            - type: string
            - type: string
              format: uuid
          title: Pay Calendar Id
      additionalProperties: true
      type: object
      required:
        - payroll_group
        - pay_group_id
        - pay_calendar_id
      title: PayrollRequest
      description: Input parameters
    CreatePayrollTaskResponse_PayrunStatus_:
      properties:
        task_id:
          type: string
          title: Task Id
        status:
          $ref: '#/components/schemas/PayrunStatus'
        payroll_status_id:
          type: string
          title: Payroll Status Id
      additionalProperties: true
      type: object
      required:
        - task_id
        - status
        - payroll_status_id
      title: CreatePayrollTaskResponse[PayrunStatus]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    payroll__gb__schema__request__PayrollRequestBase:
      properties:
        employee_id:
          anyOf:
            - type: string
            - type: string
              format: uuid
          title: Employee Id
          description: Employee identification number
        pay_details:
          $ref: '#/components/schemas/payroll__gb__schema__request__Gross'
        nic_prior_period_niable_earnings:
          anyOf:
            - items:
                anyOf:
                  - type: number
                  - type: string
                    pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
              type: array
            - type: 'null'
          title: Nic Prior Period Niable Earnings
          description: >-
            Niable earnings of each PRIOR earnings period this payment spans
            (e.g. backdated arrears for a late starter). The current period is
            derived as the period niable minus the sum of these. Each is
            assessed as its own monthly earnings period at the payment year's
            NIC thresholds (HMRC NIM08310/08312). CONTRACT: each value must be
            NIABLE earnings — net of any salary sacrifice attributable to that
            prior period — in the SAME basis as Register.niable_earnings (the
            period total). Sending gross instead of niable silently mis-splits
            the periods for sacrificing employees (they still sum to the total,
            so no error is raised). The list[Decimal] type is load-bearing:
            callers serialise money as strings and EndpointModel is
            extra='allow', so without this typed declaration the values would
            not be coerced to Decimal.
      additionalProperties: true
      type: object
      required:
        - employee_id
        - pay_details
      title: PayrollRequestBase
      description: Input parameters
    PayrunStatus:
      type: string
      enum:
        - draft
        - processing
        - approved
        - paid
      title: PayrunStatus
      description: Payrun status
    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
    payroll__gb__schema__request__Gross:
      properties:
        earnings:
          anyOf:
            - items:
                oneOf:
                  - $ref: '#/components/schemas/AmountEarnings-Input'
                  - $ref: '#/components/schemas/HoursEarnings'
                discriminator:
                  propertyName: earning_type
                  mapping:
                    AMOUNT:
                      $ref: '#/components/schemas/AmountEarnings-Input'
                    HOURS:
                      $ref: '#/components/schemas/HoursEarnings'
              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/payroll__gb__schema__request__Deductions-Input
              type: array
            - type: 'null'
          title: Deductions
        reimbursements:
          anyOf:
            - items:
                $ref: >-
                  #/components/schemas/payroll__gb__schema__request__Reimbursement-Input
              type: array
            - type: 'null'
          title: Reimbursements
      additionalProperties: true
      type: object
      required:
        - earnings
        - benefits
      title: Gross
    AmountEarnings-Input:
      properties:
        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: true
      type: object
      required:
        - wage_type_code
        - amount
      title: AmountEarnings
      description: Fixed-amount earnings (salary, bonus, allowance). Amount + frequency.
    HoursEarnings:
      properties:
        earning_type:
          type: string
          const: HOURS
          title: Earning Type
          default: HOURS
        wage_type_code:
          type: string
          title: Wage Type Code
          description: Wage type code from catalog (e.g. UK-E-002)
        hours_worked:
          anyOf:
            - type: number
              minimum: 0
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Hours Worked
          description: Number of hours worked
        hourly_rate:
          anyOf:
            - type: number
              minimum: 0
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,2}0*$
          title: Hourly Rate
          description: Hourly rate
        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 and <= hours_worked x hourly_rate when set.
      additionalProperties: true
      type: object
      required:
        - wage_type_code
        - hours_worked
        - hourly_rate
      title: HoursEarnings
      description: Hours-based earnings. Gross = hours_worked x hourly_rate.
    Benefits-Input:
      properties:
        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: true
      type: object
      required:
        - wage_type_code
      title: Benefits
    payroll__gb__schema__request__Deductions-Input:
      properties:
        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: true
      type: object
      required:
        - wage_type_code
        - amount
      title: Deductions
    payroll__gb__schema__request__Reimbursement-Input:
      properties:
        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: true
      type: object
      required:
        - wage_type_code
        - amount
      title: Reimbursement
    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 is load-bearing. Legacy callers
        (e.g. `src/payroll/gb/niccalculator.py`) look up entries in enum-keyed
        dicts using raw strings like "MONTH"; this works only because
        `hash(PayCycle.MONTH) == hash("MONTH")`. Do not change the base class
        until those callers have been migrated to pass the enum directly
        (tracked as part of the larger legacy-NIC removal).
  securitySchemes:
    BearerToken:
      type: oauth2
      flows:
        password:
          scopes:
            read:all: Read all
            write:all: Write all
            read:health_check: Read health check
            write:health_check: Write health check
            read:wage_types: Read wage types
            write:wage_types: Write wage types
          tokenUrl: >-
            https://auth-preview.intermezzo.ai/authorize?audience=api-preview.intermezzo.ai

````