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

# Create employees

> Add your first employee, or load a whole payroll at once.

Ready to add employees? Send one at a time, or a whole list at once. Either way, an employee and all its satellites are created together, or not at all.

| Call | Use it for |
| - | - |
| [Create Employee](https://docs.intermezzo.ai/api-reference/preview/great-britain/create-employee.md) `POST /gb/organizations/{organization_id}/employees` | One new starter |
| [Create Employees](https://docs.intermezzo.ai/api-reference/preview/great-britain/create-employees.md) `POST /gb/organizations/{organization_id}/employees/list` | Several employees, for example when you load an existing payroll |

## Create one employee

The body holds:

* `external_ref`: optional, your own key for the employee, unique within the organization. With it, you can address the employee as `ext:{external_ref}` in every path (see [Conventions](https://docs.intermezzo.ai/preview/conventions.md#address-a-record-by-your-own-key)).
* `valid_from`: the date the first edition of every satellite starts (see [Hubs, satellites and editions](https://docs.intermezzo.ai/preview/concepts/editions.md)).
* The satellites you have data for. Only `core` is required.

Send every field the [API reference](https://docs.intermezzo.ai/api-reference/preview/great-britain/create-employee.md) marks as required for a satellite you include. Where a value can be empty, send `null` or an empty list; a field you leave out is not filled in for you.

```http Request theme={null}
POST /gb/organizations/{organization_id}/employees
```

```json Request body expandable theme={null}
{
  "external_ref": "EMP-100234",
  "valid_from": "2026-04-06",
  "core": {
    "title": null,
    "first_name": "Sam",
    "middle_name": null,
    "last_name": "Taylor",
    "maiden_name": null,
    "gender": "F",
    "birth_date": "1991-02-14",
    "marital_status": "SINGLE",
    "personal_email": "sam.taylor@example.com",
    "work_email": null,
    "phone_numbers": [
      { "phone_number": "+447911123456", "phone_type": "MOBILE", "is_primary": true }
    ]
  },
  "address": {
    "address_line_1": "12 High Street",
    "address_line_2": "Headingley",
    "address_line_3": null,
    "address_line_4": null,
    "town": "Leeds",
    "county": null,
    "postcode": "LS1 4AB",
    "country": "GB"
  },
  "job": {
    "start_date": "2026-04-06",
    "pay_group_id": "pgr_…",
    "worker_type": "EMPLOYEE",
    "director_since": null,
    "contracted_weekly_hours": 37,
    "contracted_weekdays": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"],
    "pay_basis": "SALARIED",
    "apprenticeship": null,
    "department": null,
    "ordinarily_works_in_uk": true,
    "uk_work_exclusion_reason": "NOT_APPLICABLE",
    "irregular_payment_pattern": false,
    "proration_basis": null
  },
  "tax": {
    "tax_code": "1257L",
    "rti_id": "100234",
    "student_loan_type": "PLAN_2",
    "postgraduate_loan": false,
    "p45_gross_pay": "0.00",
    "p45_tax_amount": "0.00",
    "starter_details": { "basis": "DECLARATION", "declaration": "A" }
  },
  "insurance": {
    "national_insurance_number": "QQ123456C",
    "nic_category": "A"
  }
}
```

`job.pay_group_id` is the pay group Intermezzo set up for you.

The response is `201` with the hub and the satellites you sent, each with its `edition`. A satellite you did not send is `null`.

> [!WARNING]
>
> Every later call names the employee by its `id` (`emp_…`) or by `ext:{external_ref}`. If you create employees without an `external_ref`, store the `id`.

## New starter or existing employee

`tax.starter_details` tells HMRC how the employee started. It is filed on the employee's first FPS only.

| `basis` | Use it for |
| - | - |
| `DECLARATION` | A new employee who completed HMRC's starter checklist. `declaration` is statement `A`, `B` or `C`. |
| `EXISTING_EMPLOYMENT` | An employee already employed under this PAYE reference, moved from another payroll provider. HMRC already has the employment. Send the payroll ID the previous provider reported as `rti_id`. |
| `SECONDED` | An employee seconded to work in the UK, who completed the expatriate checklist |

When you load an existing payroll, every employee who was already paid under this PAYE reference uses `EXISTING_EMPLOYMENT`. A transfer from another employer (TUPE) is a new employee.

## Create several employees

The body is a list of the same objects. Each employee is created on its own:

* An employee that fails, whether on a business rule such as a duplicate `external_ref` or on a schema error such as an unknown field, is reported with its errors. The others are still created.
* The response is `200` even when some employees fail.

```http Request theme={null}
POST /gb/organizations/{organization_id}/employees/list

[
  { "external_ref": "EMP-100234", "valid_from": "2026-04-06", "core": { "…": "…" } },
  { "external_ref": "EMP-100117", "valid_from": "2026-04-06", "core": { "…": "…" } },
  { "external_ref": "EMP-100235", "valid_from": "2026-04-06", "core": { "…": "…" } }
]
```

```json Response theme={null}
{
  "total": 3,
  "succeeded": 2,
  "failed": 1,
  "unprocessed": 0,
  "data": [
    { "id": "emp_…", "external_ref": "EMP-100234", "…": "…" }
  ],
  "errors": [
    {
      "input_index": 1,
      "errors": [
        { "code": "HUB_DUPLICATE_EXTERNAL_REF", "field": "external_ref", "…": "…" }
      ]
    }
  ]
}
```

* `input_index` is the position of the employee in your list.
* `field` is relative to that employee, for example `tax.tax_code`.
* Check `failed` and `errors` in every response, then resend only the failed employees.

`external_ref` is unique within the organization: sending an employee whose `external_ref` already exists fails with `409 HUB_DUPLICATE_EXTERNAL_REF`, and `params.id` names the existing employee. So resending a list after a timeout does not create duplicates.

## Rules to check before you send

### Names

If only initials are known, put one per field (`first_name` `"J"`, `middle_name` `"M"`). Names are never shortened or changed: a name HMRC does not accept, for example one with é, a digit or a full stop, returns `422 FIELD_STRING_PATTERN_MISMATCH`. All name errors in a request come back together.

### NI number

> [!WARNING]
>
> The API checks only the length. Check the HMRC format yourself before you send it: two prefix letters, six digits, suffix A–D, upper case, no spaces (`QQ123456C`). A wrong format fails when the FPS is built, after payroll has been approved.

### Freeport and Investment Zone letters

The NI category letters `F`, `I`, `L`, `S`, `N`, `E`, `D` and `K` also need `job.workplace_postcode`. A payroll that needs the postcode and has none can't be approved.

### Payroll ID

Send your own `rti_id`: the payroll ID (works number) HMRC sees on the FPS. It must be unique within the organization (`409 GB_RTI_ID_DUPLICATE`) and must not be reused (`422 GB_RTI_ID_REUSED_IN_TAX_YEAR`).

If you don't have all the details yet, you can still create the employee; see [Incomplete data](https://docs.intermezzo.ai/preview/gb/employees/incomplete-data.md).


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