> For the complete documentation index, see [llms.txt](https://docs.360dialog.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.360dialog.com/docs/inbox/inbox-api/contacts.md).

# Contacts

Who you are talking to, and how to identify them.

## Find a person

Everyone who has messaged your number is a person in the Inbox. Search by name, or by the exact WhatsApp ID:

```bash
curl -H "Authorization: Token $SERVICE_TOKEN" "$INBOX/api/v1/persons/?search=anna"
```

To get one person, use [`GET /api/v1/persons/{wa_id}/`](/docs/inbox/inbox-api/api-ref/persons.md#get-api-v1-persons-wa_id).

Reference: [List persons](/docs/inbox/inbox-api/api-ref/persons.md#get-api-v1-persons)

## Identifying a person

WhatsApp users can set a username and keep their phone number hidden from businesses. When they do, you may never see their number — so the Inbox cannot rely on phone numbers to identify people. Every contact, chat and message carries three identifiers instead:

| Field          | What it is                                                                                                                                                                                                                    | Always there?                         |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `wa_id`        | The ID the API uses everywhere: in paths such as `/chats/{wa_id}/`, in the `wa_id` filter on `/messages/`, and as the recipient when you send. It is the phone number when WhatsApp shares it, and the BSUID when it does not | Yes                                   |
| `bsuid`        | The Business-Scoped User ID: a stable ID WhatsApp assigns to this person for your business portfolio, such as `US.13491208655302741918`                                                                                       | Yes, once the person has messaged you |
| `phone_number` | The phone number, in international format without `+`                                                                                                                                                                         | Only when WhatsApp shares it          |

### What to store

* **Store `bsuid`** as your long-term key for a person. It does not depend on whether WhatsApp shows you their number.
* **Store `wa_id`** alongside it, and use it for API calls. Pass it back exactly as you received it.
* **Treat `phone_number` as optional** profile data. Do not use it as a key, and do not build logic that assumes every chat has one.

### Things that break if you assume phone numbers

* Validating `wa_id` as digits only — a BSUID contains a country prefix and a dot, and can include `ENT`, as in `US.ENT.11815799212886844830`
* Matching incoming chats to your CRM by phone number only — match on `bsuid` first, and fall back to `phone_number` when it is present
* Deriving country or formatting a number for display from `wa_id`

In webhook payloads, the BSUID arrives in the standard WhatsApp fields, such as `contacts[].user_id` and `messages[].from_user_id`.

When and why WhatsApp shares or hides a phone number — including the 30-day window and Meta's contact book — is explained in [Usernames & BSUID](https://docs.360dialog.com/docs/resources/phone-numbers/usernames-and-bsuid).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.360dialog.com/docs/inbox/inbox-api/contacts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.