Skip to content

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.

Get a user by Optlo ID:

Terminal window
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:

Terminal window
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 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:

Terminal window
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 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.

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.