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

# Move Employees

> Move employees, with all their pay items, from `from_payrun_id` to this pay run.

`from_payrun_id` must name another run than this one (otherwise 422 `INVALID_FIELD_DEPENDENCY`
on `from_payrun_id`). Both runs must be of the same pay calendar and pay group (otherwise 422
`INVALID_REFERENCE` on `from_payrun_id`, `params.reason` `OTHER_PARENT`), and both must be
DRAFT: a run that is not, one being calculated included, is refused with 409
`INVALID_TRANSITION`, naming the source when it is not DRAFT, else the target. Either may be the
MAIN run. Each named employee must hold pay items in `from_payrun_id`. Every pay item the
employee holds there moves: the items added to that run and, from the run that pays their salary
and statutory pay for the period, the standing and calculated pay items it wrote when it
calculated them. Those make this run pay the employee's salary and statutory pay for the period
instead. Moving an employee out of a run that holds only items added to it, such as back to the
MAIN run, moves those items alone. Their payslips in both runs are deleted, so calculate both
runs again before approving them.

Refused whole, moving nobody (409), for an employee when all of these hold:
`from_payrun_id` is the MAIN run and pays their salary and statutory pay for the
period, it holds none of their standing or calculated pay items, and it holds no
payslip for them: it has not calculated them yet. Calculate it first, so those items
exist and move with the employee. Moving out of a supplementary run is never refused
for this reason. Also refused whole (409) when two pay items of an employee
would share a wage type code and `external_ref` in this run, or for an employee
calculated with prior-period NI-able earnings supplied through submit, and (409
`GB_MAIN_PAY_ITEMS_HOLD_NMW_HOURS`) for an employee moved out of a positive pay MAIN
run whose minimum wage hours an approved supplementary run of the period left to the
MAIN run (a draft one has its payslip for them deleted, to calculate again), and (409
`RESULT_NOT_CALCULATED`, `params.reason` `OTHER_RUN_CALCULATING`) while a run of the
period is being calculated for such an employee.



## OpenAPI

````yaml /api-reference/preview.json post /gb/organizations/{organization_id}/payruns/{payrun_id}/employees/move
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}/payruns/{payrun_id}/employees/move:
    post:
      tags:
        - Great Britain
        - Pay Runs
      summary: Move Employees
      description: >-
        Move employees, with all their pay items, from `from_payrun_id` to this
        pay run.


        `from_payrun_id` must name another run than this one (otherwise 422
        `INVALID_FIELD_DEPENDENCY`

        on `from_payrun_id`). Both runs must be of the same pay calendar and pay
        group (otherwise 422

        `INVALID_REFERENCE` on `from_payrun_id`, `params.reason`
        `OTHER_PARENT`), and both must be

        DRAFT: a run that is not, one being calculated included, is refused with
        409

        `INVALID_TRANSITION`, naming the source when it is not DRAFT, else the
        target. Either may be the

        MAIN run. Each named employee must hold pay items in `from_payrun_id`.
        Every pay item the

        employee holds there moves: the items added to that run and, from the
        run that pays their salary

        and statutory pay for the period, the standing and calculated pay items
        it wrote when it

        calculated them. Those make this run pay the employee's salary and
        statutory pay for the period

        instead. Moving an employee out of a run that holds only items added to
        it, such as back to the

        MAIN run, moves those items alone. Their payslips in both runs are
        deleted, so calculate both

        runs again before approving them.


        Refused whole, moving nobody (409), for an employee when all of these
        hold:

        `from_payrun_id` is the MAIN run and pays their salary and statutory pay
        for the

        period, it holds none of their standing or calculated pay items, and it
        holds no

        payslip for them: it has not calculated them yet. Calculate it first, so
        those items

        exist and move with the employee. Moving out of a supplementary run is
        never refused

        for this reason. Also refused whole (409) when two pay items of an
        employee

        would share a wage type code and `external_ref` in this run, or for an
        employee

        calculated with prior-period NI-able earnings supplied through submit,
        and (409

        `GB_MAIN_PAY_ITEMS_HOLD_NMW_HOURS`) for an employee moved out of a
        positive pay MAIN

        run whose minimum wage hours an approved supplementary run of the period
        left to the

        MAIN run (a draft one has its payslip for them deleted, to calculate
        again), and (409

        `RESULT_NOT_CALCULATED`, `params.reason` `OTHER_RUN_CALCULATING`) while
        a run of the

        period is being calculated for such an employee.
      operationId: >-
        move_employees_gb_organizations__organization_id__payruns__payrun_id__employees_move_post
      parameters:
        - in: path
          name: organization_id
          required: true
          schema:
            title: Organization Id
            type: string
        - in: path
          name: payrun_id
          required: true
          schema:
            title: Payrun Id
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayrunMoveRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayrunMoveResponse'
          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.
                PAYRUN_NOT_FOUND:
                  summary: Raised when a payrun is not found.
                  value:
                    errors:
                      - code: PAYRUN_NOT_FOUND
                        message: Raised when a payrun 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
                            - PAYRUN_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.

            - `PAYRUN_NOT_FOUND`: Raised when a payrun is not found.
        '409':
          content:
            application/json:
              examples:
                DUPLICATE_DEFINING_ATTRIBUTES:
                  summary: >-
                    Raised when a move would put two pay items with the same key
                    (wage type code and `external_ref`) for one employee into
                    one pay run.
                  value:
                    errors:
                      - code: DUPLICATE_DEFINING_ATTRIBUTES
                        message: >-
                          Raised when a move would put two pay items with the
                          same key (wage type code and `external_ref`) for one
                          employee into one pay run.
                GB_MAIN_PAY_ITEMS_HOLD_NMW_HOURS:
                  summary: >-
                    Raised when deleting or moving pay items would leave a
                    positive pay main run with no pay items for an employee
                    whose contracted hours an approved supplementary run of the
                    period left to the main run's minimum wage check: they would
                    then be tested in no run.
                  value:
                    errors:
                      - code: GB_MAIN_PAY_ITEMS_HOLD_NMW_HOURS
                        message: >-
                          Raised when deleting or moving pay items would leave a
                          positive pay main run with no pay items for an
                          employee whose contracted hours an approved
                          supplementary run of the period left to the main run's
                          minimum wage check: they would then be tested in no
                          run.
                GB_NIC_PRIORS_WOULD_BE_LOST:
                  summary: >-
                    Raised when pay items are added for, or a move names,
                    employees whose current payslip in the pay run was
                    calculated with NIC prior-period niable earnings supplied
                    through submit.
                  value:
                    errors:
                      - code: GB_NIC_PRIORS_WOULD_BE_LOST
                        message: >-
                          Raised when pay items are added for, or a move names,
                          employees whose current payslip in the pay run was
                          calculated with NIC prior-period niable earnings
                          supplied through submit.
                INVALID_TRANSITION:
                  summary: >-
                    Raised when a pay run that is not DRAFT is changed: pay
                    items added or deleted, the run calculated or cancelled, or
                    employees moved into or out of it.
                  value:
                    errors:
                      - code: INVALID_TRANSITION
                        message: >-
                          Raised when a pay run that is not DRAFT is changed:
                          pay items added or deleted, the run calculated or
                          cancelled, or employees moved into or out of it.
                RESULT_NOT_CALCULATED:
                  summary: >-
                    Raised when employees are moved out of the pay run that
                    holds their standing and calculated pay items for the period
                    before that run has calculated them.
                  value:
                    errors:
                      - code: RESULT_NOT_CALCULATED
                        message: >-
                          Raised when employees are moved out of the pay run
                          that holds their standing and calculated pay items for
                          the period before that run has calculated them.
                        params:
                          employee_ids:
                            - emp_01j0000000e008000000000002
                          reason: NOT_CALCULATED
                          run_id: run_01j0000000e008000000000001
                RESULT_NOT_CALCULATED (OTHER_RUN_CALCULATING):
                  summary: >-
                    Raised when deleting or moving pay items would leave a
                    positive pay main run with no pay items for employees whom a
                    supplementary run of the same pay calendar and pay group is
                    being calculated for.
                  value:
                    errors:
                      - code: RESULT_NOT_CALCULATED
                        message: >-
                          Raised when deleting or moving pay items would leave a
                          positive pay main run with no pay items for employees
                          whom a supplementary run of the same pay calendar and
                          pay group is being calculated for.
                        params:
                          reason: OTHER_RUN_CALCULATING
                          run_id: run_01j0000000e008000000000001
                          run_ids:
                            - run_01j0000000e008000000000001
              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:
                            - INVALID_TRANSITION
                            - RESULT_NOT_CALCULATED
                            - GB_NIC_PRIORS_WOULD_BE_LOST
                            - DUPLICATE_DEFINING_ATTRIBUTES
                            - GB_MAIN_PAY_ITEMS_HOLD_NMW_HOURS
                          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: >-
            - `INVALID_TRANSITION`: Raised when a pay run that is not DRAFT is
            changed: pay items added or deleted, the run calculated or
            cancelled, or employees moved into or out of it.

            - `RESULT_NOT_CALCULATED`: Raised when employees are moved out of
            the pay run that holds their standing and calculated pay items for
            the period before that run has calculated them.

            - `GB_NIC_PRIORS_WOULD_BE_LOST`: Raised when pay items are added
            for, or a move names, employees whose current payslip in the pay run
            was calculated with NIC prior-period niable earnings supplied
            through submit.

            - `DUPLICATE_DEFINING_ATTRIBUTES`: Raised when a move would put two
            pay items with the same key (wage type code and `external_ref`) for
            one employee into one pay run.

            - `GB_MAIN_PAY_ITEMS_HOLD_NMW_HOURS`: Raised when deleting or moving
            pay items would leave a positive pay main run with no pay items for
            an employee whose contracted hours an approved supplementary run of
            the period left to the main run's minimum wage check: they would
            then be tested in no run.

            - `RESULT_NOT_CALCULATED`: Raised when deleting or moving pay items
            would leave a positive pay main run with no pay items for employees
            whom a supplementary run of the same pay calendar and pay group is
            being calculated for.
        '422':
          content:
            application/json:
              examples:
                INVALID_FIELD_DEPENDENCY:
                  summary: >-
                    Raised when employees are moved from a pay run to itself:
                    `from_payrun_id` must differ from the `payrun_id` path
                    parameter, which names the target.
                  value:
                    errors:
                      - code: INVALID_FIELD_DEPENDENCY
                        message: >-
                          Raised when employees are moved from a pay run to
                          itself: `from_payrun_id` must differ from the
                          `payrun_id` path parameter, which names the target.
                INVALID_REFERENCE:
                  summary: >-
                    Raised when employees are moved between pay runs of
                    different pay calendars or pay groups: a move stays within
                    one period.
                  value:
                    errors:
                      - code: INVALID_REFERENCE
                        field: from_payrun_id
                        message: >-
                          Raised when employees are moved between pay runs of
                          different pay calendars or pay groups: a move stays
                          within one period.
                        params:
                          id: run_01j0000000e008000000000001
                          reason: OTHER_PARENT
                INVALID_REFERENCE (NOT_IN_RUN):
                  summary: >-
                    Raised when a request names employees outside the pay run's
                    population: the employees with DRAFT pay elements in it and,
                    for a MAIN run of a net change pay group, the members of its
                    pay group that no supplementary run of the period owns.
                  value:
                    errors:
                      - code: INVALID_REFERENCE
                        field: employee_ids
                        message: >-
                          Raised when a request names employees outside the pay
                          run's population: the employees with DRAFT pay
                          elements in it and, for a MAIN run of a net change pay
                          group, the members of its pay group that no
                          supplementary run of the period owns.
                        params:
                          employee_ids:
                            - emp_01j0000000e008000000000002
                          reason: NOT_IN_RUN
                          run_id: run_01j0000000e008000000000001
              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:
                            - INVALID_FIELD_DEPENDENCY
                            - INVALID_REFERENCE
                            - 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.

            - `INVALID_FIELD_DEPENDENCY`: Raised when employees are moved from a
            pay run to itself: `from_payrun_id` must differ from the `payrun_id`
            path parameter, which names the target.

            - `INVALID_REFERENCE`: Raised when employees are moved between pay
            runs of different pay calendars or pay groups: a move stays within
            one period.

            - `INVALID_REFERENCE`: Raised when a request names employees outside
            the pay run's population: the employees with DRAFT pay elements in
            it and, for a MAIN run of a net change pay group, the members of its
            pay group that no supplementary run of the period owns.
      security:
        - BearerToken: []
components:
  schemas:
    PayrunMoveRequest:
      additionalProperties: false
      properties:
        employee_ids:
          description: >-
            The employees to move, each holding pay items in `from_payrun_id`.
            All their pay items in that run move, standing and calculated ones
            included.
          items:
            type: string
          minItems: 1
          title: Employee Ids
          type: array
        from_payrun_id:
          description: >-
            The run the employees move from: DRAFT, of the same pay calendar and
            pay group as the run they move to.
          title: From Payrun Id
          type: string
      required:
        - employee_ids
        - from_payrun_id
      title: PayrunMoveRequest
      type: object
    PayrunMoveResponse:
      additionalProperties: false
      properties:
        moved_employee_ids:
          items:
            type: string
          title: Moved Employee Ids
          type: array
      required:
        - moved_employee_ids
      title: PayrunMoveResponse
      type: object
  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.