> ## Documentation Index
> Fetch the complete documentation index at: https://docs.intermezzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Conventions

> The few rules every request follows.

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:

```http Request theme={null}
GET /gb/organizations/ext:ACME-UK/employees/ext:EMP-100234
```

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:

```bash Header theme={null}
X-Acting-User: jane.smith@example.com
```

It is recorded as `created_by` on the employee and on every edition (see [Hubs, satellites and editions](https://docs.intermezzo.ai/preview/concepts/editions.md)). 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](https://docs.intermezzo.ai/api-reference/preview/great-britain/create-employee.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.