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

# Changing data

> Update data safely, even when someone else changed it first.

You change a satellite with one `PUT`. Each `PUT` writes one new edition for the date range you send (see [Hubs, satellites and editions](https://docs.intermezzo.ai/preview/concepts/editions.md)).

```http Request theme={null}
PUT /gb/organizations/{organization_id}/employees/{employee_id}/{satellite}
If-Match: "<edition>"
```

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

> [!WARNING]
>
> 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.

| Response | Cause |
| - | - |
| `412 EDITION_MISMATCH` | The satellite changed since you read it |
| `428 PRECONDITION_REQUIRED` | `If-Match` is missing |
| `422 PRECONDITION_MALFORMED` | `If-Match` is not one quoted edition number, for example `"6947"` |

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

```http Request theme={null}
PUT /gb/organizations/{organization_id}/employees/{employee_id}/address
If-None-Match: *
```

For a worked example, see [Change an employee](https://docs.intermezzo.ai/preview/gb/employees/change.md).


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