Skip to main content
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.

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).
  • valid_from: the date the first edition of every satellite starts (see Hubs, satellites and editions).
  • The satellites you have data for. Only core is required.
Send every field the API reference 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.
Request
Request body
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.
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. 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.
  • 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

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.