Base URL
Send every request tohttps://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 returns404, the same as an organization that does not exist.
Address a record by your own key
Organizations, employees and wage types take an optionalexternal_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
Who made the change
Send theX-Acting-User header on every POST and PUT, with the name or ID of the user in your system who made the change:
Header
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 asexternalRef. - Dates are ISO 8601 (
2026-04-06). - Money amounts are strings with two decimal places (
"3150.00").
Request IDs
Every response has anx-request-id header. Quote it when you contact us about a specific request.