Skip to main content
A few rules apply to every request. Once you know them, every endpoint works the same way.

Base URL

Send every request to https://preview.intermezzo.ai. Paths have no version prefix.

Country prefix

Paths start with a country code in ISO 3166-1 alpha-2 format, in lower case, for example /gb for the UK. Calls for an organization sit under /{country}/organizations/{organization_id}/.... Intermezzo is one API for many countries. Every change is sent to a country-specific endpoint, so the rules of that country apply to it. For example, an employee you send to /gb is checked against HMRC’s rules. The country comes from the path, so request bodies have no country_code. Organization responses carry country_code, for example "GB", as a read-only field.

Access

Your credentials reach only the organizations created with them. Any other organization ID returns 404, the same as an organization that does not exist.

Address a record by your own key

Organizations, employees and wage types take an optional external_ref when you create them: your own key for the record. It is unique within its parent (an employee’s external_ref within its organization), can’t be changed later, and may contain letters, digits and ., _, ~, -. Wherever a path takes a record’s id, you can send ext: followed by its external_ref instead: For example, for an employee of a UK organization:
Request
Both forms name the same record and work with every method, so you don’t need to store Intermezzo’s IDs.

Who made the change

Send the X-Acting-User header on every POST and PUT, with the name or ID of the user in your system who made the change:
Header
It is recorded as created_by on the employee and on every edition (see Hubs, satellites and editions). Without it, created_by is your client ID. The header is for the audit trail only; access is checked on the token.

JSON

  • Field names are snake_case.
  • Enum values are UPPER_SNAKE_CASE (SINGLE, MONTH), except codes an authority defines, which keep their official form. In the UK, for example, that is gender (M, F) and the NI category letters.
  • Unknown or misspelled fields are rejected with 422 FIELD_UNKNOWN, at every level of the body. That includes camelCase keys such as externalRef.
  • Dates are ISO 8601 (2026-04-06).
  • Money amounts are strings with two decimal places ("3150.00").

Request IDs

Every response has an x-request-id header. Quote it when you contact us about a specific request.

API reference

The API reference describes every call field by field. It is published from the same release as the preview environment. Use the endpoints in your country’s group, for example Great Britain for the UK.