> For the complete documentation index, see [llms.txt](https://flapjax.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flapjax.gitbook.io/docs/rest-api/guides/put-vs-patch.md).

# PUT vs PATCH

The API supports two types of updates for both people and records. Understanding the difference is important to avoid accidentally clearing data.

## PUT — Full Replacement

A `PUT` request **replaces the entire entity**. Every field you omit from the request body is set to `nil` (cleared).

Use PUT when you want to ensure the entity matches your request exactly, with no leftover values from previous updates.

Example: If a person has `first_name`, `last_name`, and `email` set, and you send a PUT with only `first_name`:

```json
PUT /v1/people/user-001

{
  "first_name": "Jane"
}
```

Result: `first_name` is "Jane", but `last_name` and `email` are now cleared to `nil`.

## PATCH — Partial Update

A `PATCH` request **only updates the fields you include**. Any fields you omit remain unchanged.

Use PATCH when you want to update specific fields without affecting the rest of the entity.

Example: Same starting state — person has `first_name`, `last_name`, and `email`. You send a PATCH with only `first_name`:

```json
PATCH /v1/people/user-001

{
  "first_name": "Jane"
}
```

Result: `first_name` is updated to "Jane", while `last_name` and `email` keep their existing values.

## When to Use Which

| Scenario                                     | Method    |
| -------------------------------------------- | --------- |
| You have the full entity and want to sync it | **PUT**   |
| You only want to change one or two fields    | **PATCH** |
| You want to clear a field by omitting it     | **PUT**   |
| You're unsure and want to be safe            | **PATCH** |

## Applies To

Both People and Records endpoints support PUT and PATCH:

* `PUT /v1/people/:external_id` and `PUT /v1/people/internal/:uuid`
* `PATCH /v1/people/:external_id` and `PATCH /v1/people/internal/:uuid`
* `PUT /v1/stacks/:stack_key/:external_id` and `PUT /v1/stacks/:stack_key/internal/:record_id`
* `PATCH /v1/stacks/:stack_key/:external_id` and `PATCH /v1/stacks/:stack_key/internal/:record_id`

{% hint style="info" %}
Note: Record updates (both PUT and PATCH) are only available for **Item** stacks. Event stacks are immutable after creation.
{% endhint %}