Skip to main content
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: 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. 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.
Edition
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).
  • created_by: who wrote it. That is the user named in X-Acting-User (see Conventions), 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

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