Skip to main content
You change a satellite with one PUT. Each PUT writes one new edition for the date range you send (see Hubs, satellites and editions).
Request
There is no POST or DELETE on a satellite. The examples on this page use the UK (/gb) endpoints. Changes work the same way under every country prefix.

Send the whole satellite

A PUT replaces the satellite’s values for the range. Send every field, not just the one that changed.
  • A field you leave out is not carried over from the previous edition. The PUT returns 422 FIELD_REQUIRED.
  • Where a value can be empty, send null or an empty list.
  • Leave out the read-only fields the GET returns, such as edition, created_at and created_by. Sending one returns 422 FIELD_UNKNOWN.

Choose the date range

Send both valid_from and valid_to. Use 9999-12-31 for a change that applies until further notice. The range must lie inside one existing edition. To change a value from 1 December onwards, send valid_from 2026-12-01 with the valid_to of the edition that covers 1 December. If a later edition already exists, for example one from 1 March, your change stops where it starts. The later edition keeps its own value. To change that value too, send a second PUT for the later edition’s range, with that edition’s If-Match.
  • A range that crosses an edition boundary returns 422 RANGE_CROSSES_EDITION.
  • A valid_from before the satellite’s first edition returns 422 VALUE_OUT_OF_RANGE.
Future dates and backdated corrections both work. The next payroll calculation uses the corrected values for the periods it covers.

Send If-Match

Send If-Match with the edition of the edition your range lies in. You get it from the employee GET (every satellite carries its edition) or from the ETag header of a satellite GET. If-Match protects you from overwriting a change you haven’t seen. If someone else wrote the satellite after you read it, for example the tax authority sending a new tax code (in the UK, HMRC), your PUT is rejected. Read the satellite again, check the new values, and decide whether to send your change.

Write a satellite for the first time

To write a satellite that does not exist yet, send If-None-Match: * instead of If-Match, on a range that runs to 9999-12-31. If the satellite already exists, the PUT returns 412 SATELLITE_EXISTS.
Request
For a worked example, see Change an employee.