> ## Documentation Index
> Fetch the complete documentation index at: https://docs.relayapp.im/llms.txt
> Use this file to discover all available pages before exploring further.

# Identifying users

> Turn a message's sender.id into the human's name and phone number.

Every inbound event already tells you *which* user it came from. A
`message.received` event carries the sender under `data.message.sender`:

```json theme={null}
"sender": { "kind": "user", "id": "usr_01JZU1F0BD" }
```

That `usr_…` id is stable: the same user always has the same id, in direct
chats and in groups. Use it to key your own records.

## Resolve the name and phone

To turn the id into something you can greet or match on, call
`GET /v1/users/{user_id}` (see the **API Reference** tab):

```bash theme={null}
curl https://api.relayapp.im/v1/users/usr_01JZU1F0BD \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN"
```

```json theme={null}
{
  "user": {
    "id": "usr_01JZU1F0BD",
    "name": "Rushil Kagithala",
    "first_name": "Rushil",
    "last_name": "Kagithala",
    "phone_number": "+13135550123",
    "avatar_url": null,
    "created_at": "2026-07-12T01:20:00.000Z"
  }
}
```

`name` is the canonical stored value. `first_name` and `last_name` are a
convenience split of `name` on the first space, so a two-word given name puts
its tail in `last_name`. Greet with them, but store `name` if you need the
exact value.

<Note>
  In a group, read `sender.id` from each `message.received` to tell participants
  apart: three users in a thread are three distinct `usr_…` ids.
</Note>

## Scope

You can only resolve a user you **currently share an active conversation
with** (direct or group). Any other id, one you have no active conversation
with or one that does not exist, returns `404`:

```json theme={null}
{ "error": { "code": "not_found", "message": "user not found" } }
```

The two cases are deliberately indistinguishable, so the endpoint can't be
used to enumerate accounts or confirm who owns a phone number. If a user
leaves the conversation or removes your agent, the lookup stops resolving them.

## Next steps

* [Developer data access and retention](/reference/data-and-permissions)
* [Conversation lifecycle](/guides/conversation-lifecycle)
* [Trust and data](/trust-and-data)