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

# Set the NEST employer for file upload

> Records the NEST employer reference and duty staging date used in NEST files. Without a connection the reference is stored as entered (source MANUAL) and can be corrected later. When the organisation is connected through NEST's web services, the reference must be the connected one and only the duty staging date is stored.



## OpenAPI

````yaml /api-reference/preview.json put /gb/organizations/{organization_id}/pension/nest/file-employer
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/file-employer:
    put:
      tags:
        - Great Britain
        - Pension
        - NEST
      summary: Set the NEST employer for file upload
      description: >-
        Records the NEST employer reference and duty staging date used in NEST
        files. Without a connection the reference is stored as entered (source
        MANUAL) and can be corrected later. When the organisation is connected
        through NEST's web services, the reference must be the connected one and
        only the duty staging date is stored.
      operationId: >-
        nest_set_file_employer_gb_organizations__organization_id__pension_nest_file_employer_put
      parameters:
        - in: path
          name: organization_id
          required: true
          schema:
            title: Organization Id
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NestManualEmployerRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NestStatusResponse'
          description: Successful Response
        '409':
          content:
            application/json:
              examples:
                NEST_EMPLOYER_REFERENCE_MISMATCH:
                  summary: >-
                    Raised when link names a NEST employer other than the one
                    the organisation is connected to.
                  value:
                    errors:
                      - code: NEST_EMPLOYER_REFERENCE_MISMATCH
                        message: >-
                          Raised when link names a NEST employer other than the
                          one the organisation is connected to.
                NEST_EMPLOYER_REFERENCE_TAKEN:
                  summary: >-
                    Raised when a NEST employer is already connected to another
                    organisation.
                  value:
                    errors:
                      - code: NEST_EMPLOYER_REFERENCE_TAKEN
                        message: >-
                          Raised when a NEST employer is already connected to
                          another organisation.
              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_EMPLOYER_REFERENCE_MISMATCH
                            - NEST_EMPLOYER_REFERENCE_TAKEN
                          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_EMPLOYER_REFERENCE_MISMATCH`: Raised when link names a NEST
            employer other than the one the organisation is connected to.

            - `NEST_EMPLOYER_REFERENCE_TAKEN`: Raised when a NEST employer is
            already connected to another organisation.
        '422':
          content:
            application/json:
              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:
                            - 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.
      security:
        - BearerToken: []
components:
  schemas:
    NestManualEmployerRequest:
      description: >-
        A NEST employer the client uploads files for, entered without contacting
        NEST.
      properties:
        duty_staging_date:
          description: The employer's auto-enrolment duties start date, as recorded in NEST
          format: date
          title: Duty Staging Date
          type: string
        employer_reference_number:
          description: The employer's NEST reference number (EMP followed by 9 digits)
          pattern: ^EMP\d{9}$
          title: Employer Reference Number
          type: string
      required:
        - employer_reference_number
        - duty_staging_date
      title: NestManualEmployerRequest
      type: object
    NestStatusResponse:
      properties:
        connection:
          anyOf:
            - $ref: '#/components/schemas/NestConnection'
            - type: 'null'
          description: The organisation's NEST employer; null when not connected
        last_operation:
          anyOf:
            - $ref: '#/components/schemas/NestLastOperation'
            - type: 'null'
          description: The latest setup, link or verify, whatever its outcome
      title: NestStatusResponse
      type: object
    NestConnection:
      properties:
        duty_staging_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: The employer's auto-enrolment duties start date
          title: Duty Staging Date
        employer_reference_number:
          title: Employer Reference Number
          type: string
        employer_status:
          anyOf:
            - $ref: '#/components/schemas/NestEmployerStatus'
            - type: 'null'
          description: >-
            NEST EmployerStatus at the last check: A = active, D = draft (set-up
            not finished), UNKNOWN = a code not recognised yet
        groups:
          items:
            $ref: '#/components/schemas/NestGroup'
          title: Groups
          type: array
        payment_sources:
          items:
            $ref: '#/components/schemas/NestPaymentSource'
          title: Payment Sources
          type: array
        readiness:
          $ref: '#/components/schemas/NestReadiness'
          description: >-
            READY when NEST reported the employer active with at least one group
            and one payment source at the last check; otherwise
            AWAITING_EMPLOYER
        source:
          $ref: '#/components/schemas/NestEmployerSource'
          default: NEST_API
          description: >-
            NEST_API: set up or linked through NEST's web services; MANUAL: the
            reference was entered for file upload and has not been checked with
            NEST
        verified_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When NEST last reported this employer's setup
          title: Verified At
      required:
        - employer_reference_number
        - readiness
      title: NestConnection
      type: object
    NestLastOperation:
      properties:
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            When FAILED: a NEST_* code naming what went wrong
            (NEST_DELEGATE_ACCESS_DENIED: the employer has not granted our
            delegate access), or another HTTP status from NEST
          title: Error Code
        error_detail:
          anyOf:
            - type: string
            - type: 'null'
          description: 'When FAILED: NEST''s error codes and messages, or our reason'
          title: Error Detail
        mode:
          $ref: '#/components/schemas/NestOperationMode'
        status:
          $ref: '#/components/schemas/NestSubmissionStatus'
        submission_id:
          title: Submission Id
          type: string
      required:
        - submission_id
        - mode
        - status
      title: NestLastOperation
      type: object
    NestEmployerStatus:
      description: >-
        NEST's EmployerStatus code, as returned by Retrieve Current Setup
        Details.


        Only A and D have been seen; any other code is recorded as UNKNOWN (the
        raw value

        stays in the NEST response kept on the pension provider audit trail).
      enum:
        - A
        - D
        - UNKNOWN
      title: NestEmployerStatus
      type: string
    NestGroup:
      description: A NEST worker group, as returned by Retrieve Current Setup Details.
      properties:
        due_date_basis:
          anyOf:
            - type: string
            - type: 'null'
          title: Due Date Basis
        eped:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          title: Eped
        frequency:
          anyOf:
            - type: string
            - type: 'null'
          title: Frequency
        name:
          title: Name
          type: string
        relative_days_after_eped:
          anyOf:
            - type: integer
            - type: 'null'
          title: Relative Days After Eped
        specific_day:
          anyOf:
            - type: string
            - type: 'null'
          title: Specific Day
        specific_day_eped_or_after:
          anyOf:
            - type: string
            - type: 'null'
          title: Specific Day Eped Or After
      required:
        - name
      title: NestGroup
      type: object
    NestPaymentSource:
      description: A NEST payment source, as returned by Retrieve Current Setup Details.
      properties:
        contribution_payment_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Contribution Payment Type
        name:
          title: Name
          type: string
      required:
        - name
      title: NestPaymentSource
      type: object
    NestReadiness:
      description: >-
        Whether an organisation's NEST employer can be used, per the last check
        with NEST.
      enum:
        - AWAITING_EMPLOYER
        - READY
      title: NestReadiness
      type: string
    NestEmployerSource:
      description: How the organisation's NEST employer row was created.
      enum:
        - NEST_API
        - MANUAL
      title: NestEmployerSource
      type: string
    NestOperationMode:
      description: What one NEST_EMPLOYER FSM does.
      enum:
        - SETUP
        - LINK
        - VERIFY
      title: NestOperationMode
      type: string
    NestSubmissionStatus:
      enum:
        - PENDING
        - SUCCESS
        - FAILED
      title: NestSubmissionStatus
      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.