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 asext:{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
coreis required.
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.
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_refor on a schema error such as an unknown field, is reported with its errors. The others are still created. - The response is
200even when some employees fail.
input_indexis the position of the employee in your list.fieldis relative to that employee, for exampletax.tax_code.- Check
failedanderrorsin 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
Freeport and Investment Zone letters
The NI category lettersF, 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 ownrti_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.