Skip to main content
Everything in Intermezzo starts with an organization: the employer that runs payroll and files with HMRC under one PAYE reference. Employees and wage types sit under it. Like an employee, an organization is a hub with satellites (see Hubs, satellites and editions).

Create the organization

Send core and the satellites you have data for in one call to Create Organization. Only core is required; valid_from is the date the first edition of every satellite starts.
Request
Request body
The response is 201 with the organization’s id (org_…). Use it, or ext:ACME-UK, in every path under /gb/organizations/{organization_id} (see Conventions). Create Organizations creates several in one call, with the same per-item results as bulk employee create. legal_name is what HMRC sees on every filing: at most 35 characters. The PAYE and Accounts Office references are checked against HMRC’s formats when you send them.

Set the HMRC login

Intermezzo files the FPS, EPS and expenses and benefits returns with the employer’s Government Gateway login. Set it with Set HMRC Credentials:
Request
Request body
The response is 204. The login is write-only: no response returns it, and there is no GET. It has no editions, so the PUT takes no If-Match. A new PUT replaces the previous login. Set the login before the first FPS is due.
Send the login again whenever the employer changes the Government Gateway password. Until you do, filings to HMRC fail.

Change the organization later

Each satellite is changed with a PUT for a date range, as described in Changing data. For example, a move of the registered office from 1 January:
Request
Request body
The PUT returns 200 with the new edition. Reads before 1 January still return the old address; reads from 1 January return the new one. To add a satellite you didn’t send at creation, for example bank, send If-None-Match: * instead of If-Match.

Check what is missing

Get Organization Status will report what still stands between the organization’s data and a completed payroll. It comes in a future release; until then it returns no findings.

Before you add employees

For now, once the organization exists, Intermezzo sets up how it is paid and its workplace pension scheme, and gives you the pay_group_id to put on each employee. Then add wage types if the catalog doesn’t cover your pay elements, and create employees.

Close an organization

Close an organization when the employer stops running payroll under this PAYE reference: it stopped trading, the PAYE scheme ends, or the payroll moves away from Intermezzo. Close it straight away if it was created by mistake.
Closing can’t be undone. A closed organization stays readable and accepts no further changes (409 HUB_CLOSED).
Closing doesn’t tell HMRC anything. Ending the PAYE scheme is a final EPS that you send yourself. Work in this order:
1

Approve the last pay run

2

Set the shutdown date

Set core.shutdown_date if the employer stopped trading.
3

Send the final EPS

Send it with the date the scheme ceased (Submit EPS).
4

Close everything under the organization

Close the employees, the organization’s wage types and its absence schemes. While any of them is open, closing the organization returns 409 OPEN_CHILDREN.
5

Close the organization