# 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](/docs/messenger/user-identification/) in the Messenger.
- **Email address** — captured from the Messenger, email, or the API.

## Looking up a user

Get a user by Optlo ID:

```sh
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:

```sh
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

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:

```sh
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

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

`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

`POST /api/v1/conversations` accepts exactly one user selector — `id`, `email`, or `externalId` — so you do not need a separate lookup:

```json
{
  "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.
