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" }
}'
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()
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']
{
"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"
}
}
{
"error": "not_found",
"message": "Identity not found or does not belong to your workspace"
}
Identities
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.
PATCH
/
api
/
v1
/
identities
/
{id}
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" }
}'
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()
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']
{
"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"
}
}
{
"error": "not_found",
"message": "Identity not found or does not belong to your workspace"
}
An identity is a known visitor: someone who gave an email through
Reading requires the
The full format is described in Errors.
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
namein lowercase or only a first name. - Flag accounts to watch. Set
is_favoritefrom a script for every identity that belongs to a target account.
Requires a secret key (
orwel_sk_) with the leads:write scope. The identity must belong to the key’s workspace.Path parameters
string
required
Identity id (UUID). Get it from List Identities, or from
identity_id on a lead.Body
Send JSON with any of these fields. Sendingnull clears a field.
string | null
Display name of the person, for example
"María López".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.boolean | null
Marks the identity as a favorite in the dashboard.
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
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' }
})
})
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. |
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" }
}'
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()
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']
{
"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"
}
}
{
"error": "not_found",
"message": "Identity not found or does not belong to your workspace"
}