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

# Request a payslip bundle

> Resolve all payruns for the given pay groups and pay-date window, validate them, and enqueue an async ZIP bundle job.  Returns 202 immediately; poll GET with the ``bundle_id`` until ``status`` is ``READY``.

The window matches each payrun's payment date: a supplementary payrun's own pay date, a main payrun's deposit date.  A supplementary run paying outside its pay calendar's period therefore belongs to the window that paid it.  Cancelled payruns are ignored, and an approved payrun with no payslips contributes nothing rather than failing the request; if no matched payrun has any payslips the request is refused as if the window matched nothing.

Bundles cover approved payruns (APPROVED or PAID) only, whose payslip PDFs are already stored.  A matched DRAFT payrun blocks the request (409); download a draft payslip one employee at a time instead.  A PROCESSING payrun blocks the request (409), as does an approved payrun whose stored PDFs are not all ready.

A bundle is identified by its window and its pay-group selection, so the same window bundled for different pay groups gives separate bundles that coexist.  Re-requesting one selection returns the existing bundle, or replaces it when the payruns it covers have changed.

For a paginated JSON view of individual payslips, use ``GET /payrolls/{payroll_status_id}/payslips`` (the ``Link: rel=bundles`` response header on that endpoint points back here).

ZIP entry names use the employee's ``external_ref`` when set; employees with no ``external_ref`` are identified by their UUID, which can be resolved via ``GET /employees``.  An entry from a supplementary payrun is suffixed ``-SUPP``, and where an employee is paid by more than one payrun on one date — a main and a supplementary run, or two runs after a pay-group move — the later entries are numbered, so every file keeps the employee's identifier.



## OpenAPI

````yaml /api-reference/preview.json post /gb/organizations/{organization_id}/payrolls/payslips/bundles
openapi: 3.2.0
info:
  description: Intermezzo's global payroll apis, organized by country
  summary: Global Payroll Platform
  title: Intermezzo Global Payroll
  version: '2026-11-18'
  x-logo:
    url: /static/icon.svg
servers:
  - description: Preview
    url: https://preview.intermezzo.ai
security: []
paths:
  /gb/organizations/{organization_id}/payrolls/payslips/bundles:
    post:
      tags:
        - Great Britain
        - Payroll
      summary: Request a payslip bundle
      description: >-
        Resolve all payruns for the given pay groups and pay-date window,
        validate them, and enqueue an async ZIP bundle job.  Returns 202
        immediately; poll GET with the ``bundle_id`` until ``status`` is
        ``READY``.


        The window matches each payrun's payment date: a supplementary payrun's
        own pay date, a main payrun's deposit date.  A supplementary run paying
        outside its pay calendar's period therefore belongs to the window that
        paid it.  Cancelled payruns are ignored, and an approved payrun with no
        payslips contributes nothing rather than failing the request; if no
        matched payrun has any payslips the request is refused as if the window
        matched nothing.


        Bundles cover approved payruns (APPROVED or PAID) only, whose payslip
        PDFs are already stored.  A matched DRAFT payrun blocks the request
        (409); download a draft payslip one employee at a time instead.  A
        PROCESSING payrun blocks the request (409), as does an approved payrun
        whose stored PDFs are not all ready.


        A bundle is identified by its window and its pay-group selection, so the
        same window bundled for different pay groups gives separate bundles that
        coexist.  Re-requesting one selection returns the existing bundle, or
        replaces it when the payruns it covers have changed.


        For a paginated JSON view of individual payslips, use ``GET
        /payrolls/{payroll_status_id}/payslips`` (the ``Link: rel=bundles``
        response header on that endpoint points back here).


        ZIP entry names use the employee's ``external_ref`` when set; employees
        with no ``external_ref`` are identified by their UUID, which can be
        resolved via ``GET /employees``.  An entry from a supplementary payrun
        is suffixed ``-SUPP``, and where an employee is paid by more than one
        payrun on one date — a main and a supplementary run, or two runs after a
        pay-group move — the later entries are numbered, so every file keeps the
        employee's identifier.
      operationId: >-
        request_payslip_bundle_gb_organizations__organization_id__payrolls_payslips_bundles_post
      parameters:
        - in: path
          name: organization_id
          required: true
          schema:
            title: Organization Id
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayslipBundleRequest'
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayslipBundleResponse'
          description: Successful Response
        '400':
          content:
            application/json:
              examples:
                ORG_BELONGS_TO_A_DIFFERENT_COUNTRY:
                  summary: >-
                    Raised when an organization belongs to a different country
                    than the one in the path.
                  value:
                    errors:
                      - code: ORG_BELONGS_TO_A_DIFFERENT_COUNTRY
                        message: >-
                          Raised when an organization belongs to a different
                          country than the one in the path.
              schema:
                properties:
                  errors:
                    items:
                      additionalProperties: false
                      description: >-
                        Represents an error that occurred during processing.


                        Designed for client-side i18n:

                        - code: Use this to look up translation (e.g.,
                        "HUB_NOT_FOUND")

                        - message: English fallback if translation not available

                        - field: Field name for form validation highlighting

                        - params: Dynamic values for translation interpolation
                      properties:
                        code:
                          description: Unique error code for i18n lookup
                          enum:
                            - ORG_BELONGS_TO_A_DIFFERENT_COUNTRY
                          title: Code
                          type: string
                        field:
                          anyOf:
                            - type: string
                            - type: 'null'
                          description: Field that caused the error
                          title: Field
                        message:
                          description: English fallback error message
                          title: Message
                          type: string
                        params:
                          anyOf:
                            - additionalProperties: true
                              type: object
                            - type: 'null'
                          description: Parameters for translation interpolation
                          title: Params
                      required:
                        - code
                        - message
                      title: ErrorDetail
                      type: object
                    type: array
                required:
                  - errors
                title: ErrorResponse
                type: object
          description: >-
            - `ORG_BELONGS_TO_A_DIFFERENT_COUNTRY`: Raised when an organization
            belongs to a different country than the one in the path.
        '404':
          content:
            application/json:
              examples:
                HUB_NOT_FOUND:
                  summary: >-
                    Raised when a hub does not exist under the parent named in
                    the path.
                  value:
                    errors:
                      - code: HUB_NOT_FOUND
                        message: >-
                          Raised when a hub does not exist under the parent
                          named in the path.
                PAY_GROUP_NOT_FOUND:
                  summary: Raised when a pay_group is not found.
                  value:
                    errors:
                      - code: PAY_GROUP_NOT_FOUND
                        message: Raised when a pay_group is not found.
              schema:
                properties:
                  errors:
                    items:
                      additionalProperties: false
                      description: >-
                        Represents an error that occurred during processing.


                        Designed for client-side i18n:

                        - code: Use this to look up translation (e.g.,
                        "HUB_NOT_FOUND")

                        - message: English fallback if translation not available

                        - field: Field name for form validation highlighting

                        - params: Dynamic values for translation interpolation
                      properties:
                        code:
                          description: Unique error code for i18n lookup
                          enum:
                            - HUB_NOT_FOUND
                            - PAY_GROUP_NOT_FOUND
                          title: Code
                          type: string
                        field:
                          anyOf:
                            - type: string
                            - type: 'null'
                          description: Field that caused the error
                          title: Field
                        message:
                          description: English fallback error message
                          title: Message
                          type: string
                        params:
                          anyOf:
                            - additionalProperties: true
                              type: object
                            - type: 'null'
                          description: Parameters for translation interpolation
                          title: Params
                      required:
                        - code
                        - message
                      title: ErrorDetail
                      type: object
                    type: array
                required:
                  - errors
                title: ErrorResponse
                type: object
          description: >-
            - `HUB_NOT_FOUND`: Raised when a hub does not exist under the parent
            named in the path.

            - `PAY_GROUP_NOT_FOUND`: Raised when a pay_group is not found.
        '409':
          content:
            application/json:
              examples:
                GB_BUNDLE_DRAFT_PAYRUN_NOT_SUPPORTED:
                  summary: >-
                    Filter matched one or more DRAFT payruns; bundles cover
                    approved payruns only.
                  value:
                    errors:
                      - code: GB_BUNDLE_DRAFT_PAYRUN_NOT_SUPPORTED
                        message: >-
                          Filter matched one or more DRAFT payruns; bundles
                          cover approved payruns only.
                GB_BUNDLE_PDFS_NOT_READY:
                  summary: >-
                    Approved payrun has payslips with no stored PDF yet; retry
                    after PDF generation completes.
                  value:
                    errors:
                      - code: GB_BUNDLE_PDFS_NOT_READY
                        message: >-
                          Approved payrun has payslips with no stored PDF yet;
                          retry after PDF generation completes.
                PAYRUN_PAYSLIPS_PROCESSING:
                  summary: >-
                    Raised when payslips are requested for a payrun that is
                    still calculating.
                  value:
                    errors:
                      - code: PAYRUN_PAYSLIPS_PROCESSING
                        message: >-
                          Raised when payslips are requested for a payrun that
                          is still calculating.
                REPORT_ALREADY_EXISTS:
                  summary: >-
                    Raised when a report of this type, period and format already
                    exists or is still being generated; `params.report_id` names
                    it.
                  value:
                    errors:
                      - code: REPORT_ALREADY_EXISTS
                        message: >-
                          Raised when a report of this type, period and format
                          already exists or is still being generated;
                          `params.report_id` names it.
              schema:
                properties:
                  errors:
                    items:
                      additionalProperties: false
                      description: >-
                        Represents an error that occurred during processing.


                        Designed for client-side i18n:

                        - code: Use this to look up translation (e.g.,
                        "HUB_NOT_FOUND")

                        - message: English fallback if translation not available

                        - field: Field name for form validation highlighting

                        - params: Dynamic values for translation interpolation
                      properties:
                        code:
                          description: Unique error code for i18n lookup
                          enum:
                            - REPORT_ALREADY_EXISTS
                            - PAYRUN_PAYSLIPS_PROCESSING
                            - GB_BUNDLE_DRAFT_PAYRUN_NOT_SUPPORTED
                            - GB_BUNDLE_PDFS_NOT_READY
                          title: Code
                          type: string
                        field:
                          anyOf:
                            - type: string
                            - type: 'null'
                          description: Field that caused the error
                          title: Field
                        message:
                          description: English fallback error message
                          title: Message
                          type: string
                        params:
                          anyOf:
                            - additionalProperties: true
                              type: object
                            - type: 'null'
                          description: Parameters for translation interpolation
                          title: Params
                      required:
                        - code
                        - message
                      title: ErrorDetail
                      type: object
                    type: array
                required:
                  - errors
                title: ErrorResponse
                type: object
          description: >-
            - `REPORT_ALREADY_EXISTS`: Raised when a report of this type, period
            and format already exists or is still being generated;
            `params.report_id` names it.

            - `PAYRUN_PAYSLIPS_PROCESSING`: Raised when payslips are requested
            for a payrun that is still calculating.

            - `GB_BUNDLE_DRAFT_PAYRUN_NOT_SUPPORTED`: Filter matched one or more
            DRAFT payruns; bundles cover approved payruns only.

            - `GB_BUNDLE_PDFS_NOT_READY`: Approved payrun has payslips with no
            stored PDF yet; retry after PDF generation completes.
        '422':
          content:
            application/json:
              examples:
                GB_BUNDLE_NO_PAYRUNS_FOR_PERIOD:
                  summary: >-
                    Raised when the period/pay-group filter matches no payruns
                    for this org.
                  value:
                    errors:
                      - code: GB_BUNDLE_NO_PAYRUNS_FOR_PERIOD
                        message: >-
                          Raised when the period/pay-group filter matches no
                          payruns for this org.
              schema:
                properties:
                  errors:
                    items:
                      additionalProperties: false
                      description: >-
                        Represents an error that occurred during processing.


                        Designed for client-side i18n:

                        - code: Use this to look up translation (e.g.,
                        "HUB_NOT_FOUND")

                        - message: English fallback if translation not available

                        - field: Field name for form validation highlighting

                        - params: Dynamic values for translation interpolation
                      properties:
                        code:
                          description: Unique error code for i18n lookup
                          enum:
                            - GB_BUNDLE_NO_PAYRUNS_FOR_PERIOD
                            - FIELD_REQUIRED
                            - FIELD_INVALID_TYPE_STRING
                            - FIELD_INVALID_TYPE_INT
                            - FIELD_INVALID_TYPE_FLOAT
                            - FIELD_INVALID_TYPE_BOOL
                            - FIELD_INVALID_TYPE_DICT
                            - FIELD_INVALID_TYPE_LIST
                            - FIELD_STRING_TOO_SHORT
                            - FIELD_STRING_TOO_LONG
                            - FIELD_STRING_PATTERN_MISMATCH
                            - FIELD_VALUE_TOO_SMALL
                            - FIELD_VALUE_TOO_LARGE
                            - FIELD_INVALID_DATE
                            - FIELD_INVALID_DATETIME
                            - FIELD_INVALID_TIME
                            - FIELD_INVALID_DATE_FORMAT
                            - FIELD_INVALID_DATETIME_FORMAT
                            - FIELD_INVALID_ENUM_VALUE
                            - FIELD_INVALID_EMAIL
                            - FIELD_INVALID_URL
                            - FIELD_LIST_TOO_SHORT
                            - FIELD_LIST_TOO_LONG
                            - FIELD_UNKNOWN
                            - FIELD_VALIDATION_ERROR
                          title: Code
                          type: string
                        field:
                          anyOf:
                            - type: string
                            - type: 'null'
                          description: Field that caused the error
                          title: Field
                        message:
                          description: English fallback error message
                          title: Message
                          type: string
                        params:
                          anyOf:
                            - additionalProperties: true
                              type: object
                            - type: 'null'
                          description: Parameters for translation interpolation
                          title: Params
                      required:
                        - code
                        - message
                      title: ErrorDetail
                      type: object
                    type: array
                required:
                  - errors
                title: ErrorResponse
                type: object
          description: >-
            The request failed validation. Type and format errors use the
            generic FIELD_* codes.

            - `GB_BUNDLE_NO_PAYRUNS_FOR_PERIOD`: Raised when the
            period/pay-group filter matches no payruns for this org.
      security:
        - BearerToken: []
components:
  schemas:
    PayslipBundleRequest:
      description: POST body for requesting a payslip bundle.
      properties:
        pay_group_ids:
          anyOf:
            - items:
                type: string
              minItems: 1
              type: array
            - type: 'null'
          description: >-
            Pay groups whose payruns are bundled. Omit or pass null to include
            all pay groups for the organisation. Pass at least one ID to filter;
            an empty list is invalid. All matched payruns must be approved
            (APPROVED or PAID).
          title: Pay Group Ids
        period_end:
          description: Last pay date to include (inclusive).
          format: date
          title: Period End
          type: string
        period_start:
          description: First pay date to include (inclusive).
          format: date
          title: Period Start
          type: string
      required:
        - period_start
        - period_end
      title: PayslipBundleRequest
      type: object
    PayslipBundleResponse:
      additionalProperties: false
      description: >-
        POST 202 and GET 200 response.


        ``download_url`` is a presigned GCS link; it is ``None`` until
        ``status`` reaches

        ``READY``.  The client polls GET with the ``bundle_id`` it received from
        POST.
      properties:
        bundle_id:
          title: Bundle Id
          type: string
        download_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Download Url
        payrun_ids:
          items:
            type: string
          title: Payrun Ids
          type: array
        status:
          $ref: '#/components/schemas/ReportStatus'
      required:
        - bundle_id
        - status
        - payrun_ids
      title: PayslipBundleResponse
      type: object
    ReportStatus:
      description: Report lifecycle, independent of the underlying Document's status.
      enum:
        - PENDING
        - GENERATING
        - READY
        - FAILED
      title: ReportStatus
      type: string
  securitySchemes:
    BearerToken:
      bearerFormat: JWT
      description: Get token from Auth0 and paste it here
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.