> ## Documentation Index
> Fetch the complete documentation index at: https://www.orwel.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Identity

> Change the name, traits, favorite flag or last seen date of a visitor identity, for example to sync CRM data back into Orwel. Only the fields you send are changed.

An identity is a known visitor: someone who gave an email through `identify()`, a form or a conversion. This endpoint edits the fields Orwel keeps about them. It is a partial update: fields you leave out of the body are not touched.

Typical uses:

* **Sync from your CRM.** Write the deal stage, owner or plan back into `traits`, so the lead in Orwel shows the same context your sales team sees.
* **Fix a name.** Forms often send `name` in lowercase or only a first name.
* **Flag accounts to watch.** Set `is_favorite` from a script for every identity that belongs to a target account.

> [!NOTE]
>
> Requires a secret key (`orwel_sk_`) with the `leads:write` scope. The identity must belong to the key's workspace.

## Path parameters

**id** `string` *required*

Identity id (UUID). Get it from [List Identities](https://www.orwel.io/docs/api-reference/identities/list.md), or from `identity_id` on a lead.

## Body

Send JSON with any of these fields. Sending `null` clears a field.

**name** `string | null`

Display name of the person, for example `"María López"`.

**traits** `object | null`

Custom attributes as a flat or nested JSON object, for example `{ "plan": "growth", "crm_stage": "proposal" }`.

**`traits` is replaced, not merged.** The object you send becomes the whole `traits` value. To add one key, read the identity first, merge your change, and send the full object. A value that is not an object (a string or an array) clears `traits`.

**is\_favorite** `boolean | null`

Marks the identity as a favorite in the dashboard.

**last\_seen** `string | null`

ISO 8601 timestamp of the last activity, for example `"2026-10-20T15:04:05Z"`. Orwel updates it with every visit; set it only when you import activity that happened outside the site.

`email`, `visitor_id`, location fields and `first_seen` cannot be changed through this endpoint. They come from the visitor's own activity.

## Updating traits without losing existing ones

```javascript JavaScript theme={null}
const id = 'ee0e8400-e29b-41d4-a716-446655440009'
const headers = {
  Authorization: 'Bearer orwel_sk_YOUR_KEY',
  'Content-Type': 'application/json'
}

// 1. Read the current traits
const { data: identity } = await fetch(`https://api.orwel.io/api/v1/identities/${id}`, { headers })
  .then((r) => r.json())

// 2. Merge and write back
await fetch(`https://api.orwel.io/api/v1/identities/${id}`, {
  method: 'PATCH',
  headers,
  body: JSON.stringify({
    traits: { ...identity.traits, crm_stage: 'proposal', owner: 'ana' }
  })
})
```

Reading requires the `visitors:read` scope on the same key.

## Response

`200` with the full identity after the update, in `data`.

| Field | Type | Description |
| - | - | - |
| `id` | string | Identity id. |
| `workspace_id` | string | Workspace the identity belongs to. |
| `visitor_id` | string \| null | Browser visitor linked to this identity. |
| `email` | string \| null | Email given by the visitor. |
| `name` | string \| null | Display name. |
| `traits` | object \| null | Custom attributes. |
| `first_seen` | string \| null | First activity, ISO 8601. |
| `last_seen` | string \| null | Last activity, ISO 8601. |
| `ip` | string \| null | Last known IP address. |
| `city`, `region`, `region_code`, `country` | string \| null | Last known location. |
| `is_favorite` | boolean \| null | Favorite flag. |
| `created_at` | string | When the identity was created, ISO 8601. |

## Errors

| Status | `error` | When |
| - | - | - |
| `400` | `bad_request` | The id is not a UUID (`details.field` is `id`), or the body is not valid JSON. |
| `401` | `unauthorized` | Missing or invalid key, or a public or development key. |
| `403` | `insufficient_scope` / `origin_not_allowed` | The key lacks the `leads:write` scope, or the request came from an origin the key does not allow. |
| `404` | `not_found` | No identity with that id in the key's workspace. |
| `429` | `rate_limit_exceeded` | Rate limit reached. See [Rate limiting](https://www.orwel.io/docs/concepts/rate-limiting.md). |

The full format is described in [Errors](https://www.orwel.io/docs/concepts/errors.md).

```bash cURL theme={null}
curl -X PATCH "https://api.orwel.io/api/v1/identities/ee0e8400-e29b-41d4-a716-446655440009" \
  -H "Authorization: Bearer orwel_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "María López",
    "is_favorite": true,
    "traits": { "plan": "growth", "crm_stage": "proposal" }
  }'
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.orwel.io/api/v1/identities/ee0e8400-e29b-41d4-a716-446655440009',
  {
    method: 'PATCH',
    headers: {
      Authorization: 'Bearer orwel_sk_YOUR_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'María López',
      is_favorite: true,
      traits: { plan: 'growth', crm_stage: 'proposal' }
    })
  }
)

const { data } = await response.json()
```

```python Python theme={null}
import requests

response = requests.patch(
    'https://api.orwel.io/api/v1/identities/ee0e8400-e29b-41d4-a716-446655440009',
    headers={'Authorization': 'Bearer orwel_sk_YOUR_KEY'},
    json={
        'name': 'María López',
        'is_favorite': True,
        'traits': {'plan': 'growth', 'crm_stage': 'proposal'},
    },
)

data = response.json()['data']
```

```json 200 OK theme={null}
{
  "data": {
    "id": "ee0e8400-e29b-41d4-a716-446655440009",
    "workspace_id": "770e8400-e29b-41d4-a716-446655440002",
    "visitor_id": "660e8400-e29b-41d4-a716-446655440001",
    "email": "maria@company.com",
    "name": "María López",
    "traits": { "plan": "growth", "crm_stage": "proposal" },
    "first_seen": "2026-10-02T17:21:09Z",
    "last_seen": "2026-10-20T15:04:05Z",
    "ip": "189.203.0.10",
    "city": "Monterrey",
    "region": "Nuevo León",
    "region_code": "NLE",
    "country": "MX",
    "is_favorite": true,
    "created_at": "2026-10-02T17:21:09Z"
  }
}
```

```json 404 Not Found theme={null}
{
  "error": "not_found",
  "message": "Identity not found or does not belong to your workspace"
}
```


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