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

# List Employees



## OpenAPI

````yaml /api-reference/preview.json get /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:
    get:
      tags:
        - Great Britain
        - Employees
      summary: List Employees
      operationId: gb_employee_list
      parameters:
        - name: organization_id
          in: path
          required: true
          schema:
            type: string
            title: Organization Id
        - name: valid_at
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date
              - type: 'null'
            description: >-
              Valid-time date to read, past or future. Defaults to today, or to
              the first upcoming edition when nothing is valid yet.
            title: Valid At
          description: >-
            Valid-time date to read, past or future. Defaults to today, or to
            the first upcoming edition when nothing is valid yet.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            default: 10
            title: Limit
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Cursor
        - name: prev_cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Prev Cursor
        - name: sort
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
            default:
              - id
            title: Sort
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_GBEmployeeSummary_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - BearerToken: []
components:
  schemas:
    PaginatedResponse_GBEmployeeSummary_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/GBEmployeeSummary'
          type: array
          title: Items
        pagination:
          $ref: '#/components/schemas/PaginationMeta'
      additionalProperties: false
      type: object
      required:
        - items
        - pagination
      title: PaginatedResponse[GBEmployeeSummary]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    GBEmployeeSummary:
      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
            `<authority>:<notice>` 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'
        job:
          anyOf:
            - $ref: '#/components/schemas/GBEmployeeJobSatellite'
            - type: 'null'
        tax:
          anyOf:
            - $ref: '#/components/schemas/GBEmployeeTaxSatellite'
            - type: 'null'
      additionalProperties: false
      type: object
      required:
        - id
        - external_ref
        - created_at
        - created_by
        - deleted_at
        - organization_id
      title: GBEmployeeSummary
      description: >-
        An employee in a list: the hub and its core, job and tax satellites as
        they read

        on the date of the list. A satellite with no slice on an explicit date
        is absent.
    PaginationMeta:
      properties:
        limit:
          type: integer
          title: Limit
        has_next:
          type: boolean
          title: Has Next
          default: false
        has_prev:
          type: boolean
          title: Has Prev
          default: false
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
        prev_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Prev Cursor
        total:
          type: integer
          title: Total
          default: 0
      additionalProperties: false
      type: object
      required:
        - limit
      title: PaginationMeta
    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
    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
            `<authority>:<notice>` 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
    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
            `<authority>:<notice>` 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
            `<authority>:<notice>` 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
    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-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).
    StudentLoanPlanType:
      type: string
      enum:
        - Plan1
        - Plan2
        - Plan4
      title: StudentLoanPlanType
      description: Types of student loan plans
    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.
  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.