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

# Generate a NEST contribution schedule (CS) file

> Builds the contribution schedule NEST created for a payment source, frequency and earnings period end date: copy them and the payment due date from the schedule in NEST. Every FILE scheme paying from the source is covered. Members are reported with the contributions of payruns paid in the earnings period, and leavers, cessations and paper opt-outs with their reason. A file of the same key that was never marked uploaded is replaced; one uploaded or approved is corrected, and the new file names it in corrects_id. When records have problems NEST would reject, the file is stored as FAILED with every problem listed and no CSV. Warnings return 422 NEST_FILE_WARNINGS unless overwrite_soft_validation is true. Files are uploaded by the client on the NEST website; Intermezzo cannot see the outcome, so the client reports it with mark-uploaded.



## OpenAPI

````yaml /api-reference/preview.json post /gb/organizations/{organization_id}/pension/nest/files/cs
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}/pension/nest/files/cs:
    post:
      tags:
        - Great Britain
        - Pension
        - NEST
      summary: Generate a NEST contribution schedule (CS) file
      description: >-
        Builds the contribution schedule NEST created for a payment source,
        frequency and earnings period end date: copy them and the payment due
        date from the schedule in NEST. Every FILE scheme paying from the source
        is covered. Members are reported with the contributions of payruns paid
        in the earnings period, and leavers, cessations and paper opt-outs with
        their reason. A file of the same key that was never marked uploaded is
        replaced; one uploaded or approved is corrected, and the new file names
        it in corrects_id. When records have problems NEST would reject, the
        file is stored as FAILED with every problem listed and no CSV. Warnings
        return 422 NEST_FILE_WARNINGS unless overwrite_soft_validation is true.
        Files are uploaded by the client on the NEST website; Intermezzo cannot
        see the outcome, so the client reports it with mark-uploaded.
      operationId: >-
        nest_generate_cs_gb_organizations__organization_id__pension_nest_files_cs_post
      parameters:
        - in: path
          name: organization_id
          required: true
          schema:
            title: Organization Id
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NestCsGenerateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NestFileResponse'
          description: Successful Response
        '400':
          content:
            application/json:
              examples:
                NEST_NOT_CONNECTED:
                  summary: >-
                    Raised when verify is requested for an organisation not
                    connected to NEST.
                  value:
                    errors:
                      - code: NEST_NOT_CONNECTED
                        message: >-
                          Raised when verify is requested for an organisation
                          not connected to NEST.
              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:
                            - NEST_NOT_CONNECTED
                          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: >-
            - `NEST_NOT_CONNECTED`: Raised when verify is requested for an
            organisation not connected to NEST.
        '422':
          content:
            application/json:
              examples:
                NEST_EPED_NOT_A_PRP_END:
                  summary: >-
                    Raised when no pay group on the schedule's frequency has a
                    PRP ending on its EPED.
                  value:
                    errors:
                      - code: NEST_EPED_NOT_A_PRP_END
                        message: >-
                          Raised when no pay group on the schedule's frequency
                          has a PRP ending on its EPED.
                NEST_FILE_CONFIG_INCOMPLETE:
                  summary: Raised when settings a NEST file needs are missing.
                  value:
                    errors:
                      - code: NEST_FILE_CONFIG_INCOMPLETE
                        message: Raised when settings a NEST file needs are missing.
                NEST_FILE_WARNINGS:
                  summary: >-
                    Raised when a NEST file has warnings and they were not
                    acknowledged.
                  value:
                    errors:
                      - code: NEST_FILE_WARNINGS
                        message: >-
                          Raised when a NEST file has warnings and they were not
                          acknowledged.
              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:
                            - NEST_FILE_CONFIG_INCOMPLETE
                            - NEST_EPED_NOT_A_PRP_END
                            - NEST_FILE_WARNINGS
                            - 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.

            - `NEST_FILE_CONFIG_INCOMPLETE`: Raised when settings a NEST file
            needs are missing.

            - `NEST_EPED_NOT_A_PRP_END`: Raised when no pay group on the
            schedule's frequency has a PRP ending on its EPED.

            - `NEST_FILE_WARNINGS`: Raised when a NEST file has warnings and
            they were not acknowledged.
      security:
        - BearerToken: []
components:
  schemas:
    NestCsGenerateRequest:
      properties:
        eped:
          description: >-
            Earnings period end date of the schedule, as NEST shows it; must be
            the end of a pension pay reference period of the pay groups on this
            frequency
          format: date
          title: Eped
          type: string
        epsd:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: >-
            Earnings period start date, copied from the NEST schedule screen.
            Sent only when given: NEST needs it only when two schedules share
            the other header values
          title: Epsd
        frequency:
          $ref: '#/components/schemas/NestFileFrequency'
          description: The schedule's frequency, as NEST shows it on the schedule
        opt_outs_confirmed:
          const: true
          description: >-
            Confirms every opt-out in the NEST mailbox was recorded in
            Intermezzo before generating; stored on the file
          title: Opt Outs Confirmed
          type: boolean
        overwrite_soft_validation:
          default: false
          description: >-
            Request-scoped, not stored as a setting: generate even when there
            are warnings. The acknowledged warnings are recorded on the file
          title: Overwrite Soft Validation
          type: boolean
        payment_due_date:
          description: The schedule's payment due date, as NEST shows it
          format: date
          title: Payment Due Date
          type: string
        payment_source_name:
          description: >-
            The NEST payment source of the schedule, as named in NEST; every
            FILE scheme paying from it is covered
          maxLength: 40
          minLength: 1
          title: Payment Source Name
          type: string
      required:
        - payment_source_name
        - frequency
        - eped
        - payment_due_date
        - opt_outs_confirmed
      title: NestCsGenerateRequest
      type: object
    NestFileResponse:
      properties:
        approved_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Approved At
        approved_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Approved By
        contributions:
          description: Contribution schedule rows
          items:
            $ref: '#/components/schemas/NestCsContributionResponse'
          title: Contributions
          type: array
        corrects_id:
          anyOf:
            - type: string
            - type: 'null'
          description: The uploaded or approved schedule of the same key it corrects
          title: Corrects Id
        created_at:
          format: date-time
          title: Created At
          type: string
        created_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Created By
        document_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Document Id
        eped:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          title: Eped
        epsd:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          title: Epsd
        file_id:
          title: File Id
          type: string
        file_type:
          $ref: '#/components/schemas/NestFileType'
        frequency:
          anyOf:
            - $ref: '#/components/schemas/NestFileFrequency'
            - type: 'null'
        members:
          description: ME and baseline members
          items:
            $ref: '#/components/schemas/NestFileMemberResponse'
          title: Members
          type: array
        opt_outs_confirmed_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Opt Outs Confirmed At
        opt_outs_confirmed_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Opt Outs Confirmed By
        payment_due_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          title: Payment Due Date
        payment_source_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Payment Source Name
        problems:
          description: Why the file could not be produced; only when FAILED
          items:
            $ref: '#/components/schemas/NestFileFinding'
          title: Problems
          type: array
        record_count:
          title: Record Count
          type: integer
        scheme_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Scheme Ids
        status:
          $ref: '#/components/schemas/NestFileStatus'
        uploaded_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Uploaded At
        uploaded_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Uploaded By
        warnings:
          description: Warnings acknowledged with overwrite_soft_validation
          items:
            $ref: '#/components/schemas/NestFileFinding'
          title: Warnings
          type: array
      required:
        - file_id
        - file_type
        - status
        - record_count
        - document_id
        - problems
        - warnings
        - members
        - created_at
        - created_by
        - uploaded_at
        - uploaded_by
      title: NestFileResponse
      type: object
    NestFileFrequency:
      description: >-
        Contribution schedule frequencies (guide 3.2.1, field 7).


        UPPER_SNAKE_CASE in the API like every enum; the file header carries
        NEST's label.
      enum:
        - WEEKLY
        - TAX_WEEKLY
        - MONTHLY
        - TAX_MONTHLY
      title: NestFileFrequency
      type: string
    NestCsContributionResponse:
      description: One member row of a contribution schedule, as sent.
      properties:
        employee_id:
          title: Employee Id
          type: string
        employer_contribution:
          title: Employer Contribution
          type: string
        enrolment_date:
          format: date
          title: Enrolment Date
          type: string
        identifier_type:
          $ref: '#/components/schemas/NestIdentifierType'
        member_contribution:
          title: Member Contribution
          type: string
        opt_out_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Opt Out Reference
        pensionable_earnings:
          title: Pensionable Earnings
          type: string
        reason:
          anyOf:
            - type: string
            - type: 'null'
          description: 'NEST reason code: 1 left, 5 no contributions due, 9 opted out'
          title: Reason
        scheme_id:
          title: Scheme Id
          type: string
      required:
        - employee_id
        - enrolment_date
        - scheme_id
        - identifier_type
        - pensionable_earnings
        - employer_contribution
        - member_contribution
        - reason
        - opt_out_reference
      title: NestCsContributionResponse
      type: object
    NestFileType:
      description: Which NEST file a row records.
      enum:
        - ME
        - CS
        - BASELINE
      title: NestFileType
      type: string
    NestFileMemberResponse:
      properties:
        employee_id:
          title: Employee Id
          type: string
        enrolment_date:
          format: date
          title: Enrolment Date
          type: string
        identifier_type:
          $ref: '#/components/schemas/NestIdentifierType'
        rejected:
          title: Rejected
          type: boolean
        resolved_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Resolved At
        scheme_id:
          title: Scheme Id
          type: string
      required:
        - employee_id
        - enrolment_date
        - scheme_id
        - identifier_type
        - rejected
        - resolved_at
      title: NestFileMemberResponse
      type: object
    NestFileFinding:
      properties:
        code:
          $ref: '#/components/schemas/NestFileFindingCode'
        employee_id:
          anyOf:
            - type: string
            - type: 'null'
          description: The employee the finding is about; null for the whole file
          title: Employee Id
        field:
          anyOf:
            - type: string
            - type: 'null'
          description: The NEST field concerned
          title: Field
        message:
          title: Message
          type: string
      required:
        - code
        - message
      title: NestFileFinding
      type: object
    NestFileStatus:
      description: >-
        Lifecycle of one generated NEST file.


        Uploads happen on the NEST website, so the UPLOADED states are set by
        the client. An ME

        is UPLOADED_ALL_ACCEPTED or UPLOADED_WITH_ERRORS; a CS, whose row errors
        are fixed online

        in NEST, is UPLOADED and then APPROVED_IN_NEST once the employer
        approves the schedule.
      enum:
        - GENERATED
        - FAILED
        - SUPERSEDED
        - UPLOADED_ALL_ACCEPTED
        - UPLOADED_WITH_ERRORS
        - UPLOADED
        - APPROVED_IN_NEST
      title: NestFileStatus
      type: string
    NestIdentifierType:
      description: Which identifier NEST matches a member on.
      enum:
        - NINO
        - ALT_ID
      title: NestIdentifierType
      type: string
    NestFileFindingCode:
      description: >-
        Why a NEST file cannot be produced (problem) or needs confirming
        (warning).
      enum:
        - MISSING_VALUE
        - INVALID_VALUE
        - TOO_LONG
        - INVALID_CHARACTERS
        - TITLE_GENDER_MISMATCH
        - DUPLICATE_NINO
        - ADDRESS_MISSING
        - ORGANIZATION_ADDRESS_MISSING
        - BEFORE_STAGING_DATE
        - FILE_TOO_LARGE
        - NEGATIVE_AMOUNT
        - NET_PAY_ARRANGEMENT
        - BASE_NOT_RECOVERABLE
        - EPSD_CONFLICT
        - EPSD_DIFFERS
        - CONTRIBUTIONS_IN_ANOTHER_SCHEME
        - START_DATE_OVER_SIX_WEEKS
        - ALPHABETIC_ALT_ID
        - IDENTIFIER_CHANGED
        - UNMARKED_PREVIOUS_FILE
        - NOT_KNOWN_TO_NEST
        - ME_REJECTED_EXCLUDED
        - EXPECTED_MEMBER_MISSING
        - LEAVER_WITHOUT_P45
        - PAID_AFTER_LEAVING
        - SCHEME_CHANGE
        - PAY_GROUP_CHANGE
        - TWO_ENROLMENTS
        - FAMILY_LEAVE
        - OPT_OUT_WITHOUT_CHANNEL
        - CESSATION_THROUGH_PROVIDER
        - UNAPPROVED_PAYRUN
        - BASE_RECOVERED
        - CONTRIBUTION_MISMATCH
        - RATES_DIFFER_FROM_SCHEME
        - NO_TAX_RELIEF
        - DUE_DATE_SOON
        - DUE_DATE_CHANGED
        - DUE_DATE_AFTER_DEADLINE
        - UPLOADED_NOT_APPROVED
        - EARLIER_SCHEDULE_NOT_UPLOADED
        - PAYRUNS_CHANGED_SINCE_APPROVAL
        - PAID_AFTER_EXIT_REPORTED
        - EXIT_REPORTED_IN_LATER_SCHEDULE
        - OPTED_OUT_WITH_DEDUCTIONS
        - DUE_DATE_SETTINGS_DIFFER
        - LEFT_PAY_GROUP_IN_WINDOW
        - CORRECTION_NEEDS_EXCEPTION_SCHEDULE
        - CORRECTION_KEEPS_APPROVED_ROW
      title: NestFileFindingCode
      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.