Skip to content

Update a user

PATCH
/users/{userId}
curl --request PATCH \
--url https://optlo.com/api/v1/users/example \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'idempotency-key: example' \
--data '{ "name": "Sam Rivera-Smith" }'

Requires users:write. The path uses the Optlo user ID. Omitted fields remain unchanged; null clears a field. attrs replaces the entire object, including when it is empty. Email addresses may be shared. External IDs can be changed or cleared; an external ID assigned to another user returns 409. Numeric and string external IDs are distinct. An empty object leaves the user unchanged. Idempotency-Key is required and retained for 24 hours; identical retries return the original response and conflicting reuse returns 409. The updated user is returned without requiring users:read.

userId
required
string

Unique identifier for the user.

Media typeapplication/json
Show child attributesHide child attributes
externalId

User identifier in your system. String and numeric IDs are distinct.

nullable
string
>= 1 characters <= 256 characters
or
number
email

User’s email address. Matching is case-insensitive.

nullable string format: email
<= 254 characters
name

User’s display name.

nullable string
>= 1 characters <= 200 characters
avatarUrl

URL of the user’s avatar image.

nullable string format: uri
<= 2048 characters
attrs

Custom user attributes. Up to 100 attributes; keys contain 1–256 characters and string values at most 4096 characters. Updating attrs replaces the entire dictionary.

nullable dictionary
Show child attributesHide child attributes
key
additional properties
nullable
string
<= 4096 characters
or
number
or
boolean

Success

Media typeapplication/json
Show child attributesHide child attributes
id
required

Unique identifier for the user.

string
name
required

User’s display name.

nullable string
email
required

User’s email address.

nullable string
externalId
required

User identifier in your system. String and numeric IDs are distinct.

nullable
string
or
number
avatarUrl
required

URL of the user’s avatar image.

nullable string
attrs
required

Custom attributes attached to the user, such as plan or company. Values can be strings, numbers, booleans, or null.

nullable dictionary
Show child attributesHide child attributes
key
additional properties
nullable
string
or
number
or
boolean
createdAt
required

Time the user was created.

string format: date-time
lastVisitedAt
required

Time of the user’s most recent visit. Null if no visit has been recorded.

nullable string format: date-time

Example

{
"id": "user_kR7mP3xB9nQ2vL5z",
"name": "Sam Rivera-Smith",
"email": "sam@example.com",
"externalId": "customer_1042",
"avatarUrl": null,
"attrs": {
"plan": "pro",
"company": "Acme"
},
"createdAt": "2026-10-13T09:00:00.000Z",
"lastVisitedAt": "2026-10-13T09:05:00.000Z"
}