> ## 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.

# Hubs, satellites and editions

> How Intermezzo keeps the history of your data, so every payroll uses the right values.

Payroll is calculated for a period, and data changes over time. For example, an employee in the UK gets a new tax code in December and moves house in March. The API keeps every value with the dates it applies, so a payroll is always calculated with the data that was valid for its period.

## Hub and satellites

A record, for example an employee, is a **hub** with **satellites**.

* The **hub** is the record's identity: its `id`, your `external_ref`, the `organization_id` and the creation details. It is written once, when the record is created.
* Each **satellite** is one group of fields with its own history and its own endpoint, for example `…/employees/{employee_id}/tax`.

Intermezzo uses the same hubs and satellites in every country, and each one keeps the same role everywhere. Which satellites a hub has depends on the country's rules.

For example, an employee of a UK organization has these satellites:

| Satellite | Holds |
| - | - |
| `core` | Name, gender, date of birth, marital status, emails, phone numbers |
| `address` | Home address, in lines with town, postcode and country |
| `job` | Start date, pay group, hours and working days, worker type, pay basis, department |
| `tax` | Payroll ID (`rti_id`), tax code, student and postgraduate loan, P45 figures from a previous employer |
| `insurance` | National Insurance number and NI category letter |
| `compensation` | Standing pay: salary and other pay paid every period (see [Compensation](https://docs.intermezzo.ai/preview/gb/employees/compensation.md)) |
| `bank` | Bank accounts for net pay |
| `status` | Read-only: what still stands between the employee's data and a completed payroll (see [Incomplete data](https://docs.intermezzo.ai/preview/gb/employees/incomplete-data.md)) |

An employee in the UAE, by contrast, has no `tax` satellite, because the UAE has no income tax.

In the UK, pension membership has its own calls; see [Pension](https://docs.intermezzo.ai/preview/gb/employees/pension.md).

A satellite that was never written does not exist: its `GET` returns `404 SATELLITE_NOT_FOUND`, and the employee `GET` shows it as `null`.

## Editions

Each change to a satellite creates a new **edition**. An edition holds the satellite's values for a date range:

* `valid_from` is the first day the values apply. It is included in the range.
* `valid_to` is the first day they no longer apply. It is excluded from the range.
* `valid_to` `9999-12-31` means the values apply until further notice.

Earlier editions are kept. Payroll uses the edition that is valid on the pay date. For example, a recalculated March payroll in the UK still uses March's tax code after the April change has been sent.

```json Edition theme={null}
{
  "valid_from": "2026-04-06",
  "valid_to": "2026-12-01",
  "edition": 6947,
  "created_at": "2026-04-02T09:14:31Z",
  "created_by": "jane.smith@example.com",
  "tax_code": "1257L"
}
```

Every edition carries:

* `edition`: a number that identifies the edition. You send it back, in quotes, in `If-Match` when you change the satellite (see [Changing data](https://docs.intermezzo.ai/preview/concepts/changing-data.md)).
* `created_by`: who wrote it. That is the user named in `X-Acting-User` (see [Conventions](https://docs.intermezzo.ai/preview/conventions.md#who-made-the-change)), your client ID when the header was missing, `system` for Intermezzo, or the tax authority notice that changed it. In the UK, for example, that is `hmrc:P6` when HMRC sends a new tax code.

## Read a satellite and its history

| Call | Returns |
| - | - |
| `GET …/{employee_id}/{satellite}` | The edition valid today, or the first upcoming one if none is valid yet |
| `GET …/{employee_id}/{satellite}?valid_at=2026-12-15` | The edition valid on that date, past or future. A date outside the range the satellite covers returns `422 VALUE_OUT_OF_RANGE`. |
| `GET …/{employee_id}/{satellite}/editions` | The timeline: which values apply from when to when, with corrections applied |
| `GET …/{employee_id}/{satellite}/protocol` | Every edition ever written, in the order written, including the ones later corrected |

Use `/editions` to see what applies when. Use `/protocol` to see what was sent and when, for example to trace a correction. Both lists are paginated (see [Pagination](https://docs.intermezzo.ai/preview/concepts/pagination.md)).


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