Finding users
Optlo identifies each user in three ways:
- Optlo ID — assigned by Optlo, such as
user_…. It never changes. - External ID — your system’s identifier for the person, set through the API or user identification in the Messenger.
- Email address — captured from the Messenger, email, or the API.
Looking up a user
Section titled “Looking up a user”Get a user by Optlo ID:
curl https://optlo.com/api/v1/users/USER_ID \ -H "Authorization: Bearer YOUR_API_KEY"Find users by external ID or email with the list endpoint:
curl "https://optlo.com/api/v1/users?externalId=crm-4821" \ -H "Authorization: Bearer YOUR_API_KEY"
curl "https://optlo.com/api/v1/users?email=sam@example.com" \ -H "Authorization: Bearer YOUR_API_KEY"Lookups require users:read. The list endpoint returns a page of matches, which is empty when nothing matches.
External IDs
Section titled “External IDs”External IDs match exactly. Numeric and string external IDs are distinct: the number 4821 and the string "4821" identify different users. The externalId query parameter is treated as a string by default; add externalIdKind=number to match a numeric ID:
curl "https://optlo.com/api/v1/users?externalId=4821&externalIdKind=number" \ -H "Authorization: Bearer YOUR_API_KEY"Each external ID belongs to at most one user, so an external ID lookup returns zero or one users.
Email addresses
Section titled “Email addresses”Email matching is case-insensitive. More than one user can share an email address — for example, a person who used the Messenger anonymously and later through your signed-in app — so an email lookup can return several users. Prefer external IDs when your system has them.
Creating users without duplicates
Section titled “Creating users without duplicates”POST /api/v1/users never updates an existing user. It returns 409 conflict instead of creating a duplicate:
- With
externalId, an existing user with that external ID conflicts. A new external ID creates a separate user even if the email address is already in use. - Without
externalId, any user with the same email address conflicts.
A sync job can create the user first and, on 409, look the user up and update it with PATCH /api/v1/users/{userId}. Updates require the Optlo ID.
Starting conversations with a user selector
Section titled “Starting conversations with a user selector”POST /api/v1/conversations accepts exactly one user selector — id, email, or externalId — so you do not need a separate lookup:
{ "user": { "externalId": "crm-4821" }, "message": { "content": "Your order has shipped.", "sender": { "role": "operator", "id": "OPERATOR_ID" } }}The selector must match an existing user; no match returns 404 not_found, and an email that matches several users returns 409 conflict. Conversation creation never creates or updates users.