Skip to content

Create a user

POST
/users
curl --request POST \
--url https://optlo.com/api/v1/users \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'idempotency-key: example' \
--data '{ "name": "Sam Rivera", "email": "sam@example.com", "externalId": "customer_1042", "attrs": { "plan": "pro", "company": "Acme" } }'

Requires users:write. Supply externalId or email. When externalId is supplied, an existing external ID returns 409; a new external ID creates a separate user even if the email is already used. Without externalId, any case-insensitive email match returns 409. Existing users are never updated. Numeric and string external IDs are distinct. Idempotency-Key is required and retained for 24 hours; identical retries return the original user and conflicting reuse returns 409. The created user is returned without requiring users:read. Creation consumes one daily user allowance atomically with persistence; exhaustion returns 429 daily_limit_exceeded. Identity conflicts and retained idempotent retries consume no additional capacity.

Media typeapplication/json
Show child attributesHide child attributes
externalId

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

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

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

string format: email
<= 254 characters
name

User’s display name.

string
>= 1 characters <= 200 characters
avatarUrl

URL of the user’s avatar image.

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.

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

Created

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",
"email": "sam@example.com",
"externalId": "customer_1042",
"avatarUrl": null,
"attrs": {
"plan": "pro",
"company": "Acme"
},
"createdAt": "2026-10-13T09:00:00.000Z",
"lastVisitedAt": null
}