Hub and satellites
A record, for example an employee, is a hub with satellites.- The hub is the record’s identity: its
id, yourexternal_ref, theorganization_idand 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.
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_fromis the first day the values apply. It is included in the range.valid_tois the first day they no longer apply. It is excluded from the range.valid_to9999-12-31means the values apply until further notice.
Edition
edition: a number that identifies the edition. You send it back, in quotes, inIf-Matchwhen you change the satellite (see Changing data).created_by: who wrote it. That is the user named inX-Acting-User(see Conventions), your client ID when the header was missing,systemfor Intermezzo, or the tax authority notice that changed it. In the UK, for example, that ishmrc:P6when 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).