PUT. Each PUT writes one new edition for the date range you send (see Hubs, satellites and editions).
Request
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 field you leave out is not carried over from the previous edition. The
PUTreturns422 FIELD_REQUIRED. - Where a value can be empty, send
nullor an empty list. - Leave out the read-only fields the
GETreturns, such asedition,created_atandcreated_by. Sending one returns422 FIELD_UNKNOWN.
Choose the date range
Send bothvalid_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_frombefore the satellite’s first edition returns422 VALUE_OUT_OF_RANGE.
Send If-Match
SendIf-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, sendIf-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