Create a user
const url = 'https://optlo.com/api/v1/users';const options = { method: 'POST', headers: { 'idempotency-key': 'example', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"name":"Sam Rivera","email":"sam@example.com","externalId":"customer_1042","attrs":{"plan":"pro","company":"Acme"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”Show child attributes
User identifier in your system. String and numeric IDs are distinct.
User’s email address. Matching is case-insensitive.
User’s display name.
URL of the user’s avatar image.
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.
Show child attributes
Response
Section titled “Response”Created
Show child attributes
Unique identifier for the user.
User’s display name.
User’s email address.
User identifier in your system. String and numeric IDs are distinct.
URL of the user’s avatar image.
Custom attributes attached to the user, such as plan or company. Values can be strings, numbers, booleans, or null.
Show child attributes
Time the user was created.
Time of the user’s most recent visit. Null if no visit has been recorded.
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}