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

# Working with contacts

> Find people and manage your team's CRM state about them

A contact is your team's record of a person: their status, tags, notes, valuation and default assignee. It groups one or more **profiles**, their accounts on each platform.

## Find a contact

Contacts are found by the platform identity of one of their profiles. `platform` is required, with `platformId` or `username`.

<CodeGroup>
  ```bash By platform ID theme={null}
  curl "https://inboxapp.com/api/v2/contacts?platform=twitter&platformId=1876543210987654321" \
    -H "Authorization: Bearer $INBOX_API_TOKEN"
  ```

  ```bash By username theme={null}
  curl "https://inboxapp.com/api/v2/contacts?platform=twitter&username=sarahchen" \
    -H "Authorization: Bearer $INBOX_API_TOKEN"
  ```
</CodeGroup>

```json theme={null}
{
  "data": [
    {
      "id": "nq2r8v5ycx1t7m4hj6kd3wzb",
      "profiles": [
        {
          "id": "n7kxqm5d9iu2sgdf6jbw4h36",
          "platform": "twitter",
          "platformId": "1876543210987654321",
          "username": "sarahchen",
          "handle": "@sarahchen",
          "displayName": "Sarah Chen",
          "avatarUrl": "https://pbs.twimg.com/profile_images/1876543210/sarah.jpg",
          "bio": "Head of Growth at Northwind",
          "verified": true,
          "isOrganization": false,
          "followerCount": 18400,
          "accountStatus": "active",
          "profileUrl": "https://x.com/sarahchen"
        }
      ],
      "statusId": "r3km7xj9wq5p2bvnhfdteoly",
      "tagIds": ["t9wq5p2bvnhfdteolyr3km7x"],
      "notes": "Asked for a demo of the reporting API.",
      "valuation": 12000,
      "assigneeId": null,
      "createdAt": "2026-09-01T09:00:00.000Z",
      "updatedAt": "2026-09-14T10:32:00.000Z"
    }
  ],
  "nextCursor": null
}
```

* Pass `username` without its display prefix: `sarahchen`, not `@sarahchen`.
* Repeat `platformId` or `username` to look up to 100 people in one call.
* No match is an empty `data` array. The person exists on the platform, but your team has no record of them yet.

<Note>
  A contact appears when your team first talks to someone or imports them. To
  message someone who has no contact, send with a [`profile`
  target](/v2/guides/messages#targets).
</Note>

## Get a contact

```bash theme={null}
curl "https://inboxapp.com/api/v2/contacts/nq2r8v5ycx1t7m4hj6kd3wzb?expand=status&expand=tags&expand=assignee" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"
```

`expand` embeds the `status`, `tags` and `assignee` next to their IDs.

## Update a contact

`PATCH` only what changes. `null` clears a field.

```typescript update.ts theme={null}
async function qualify(contactId: string) {
  const response = await fetch(
    `https://inboxapp.com/api/v2/contacts/${contactId}`,
    {
      method: "PATCH",
      headers: {
        Authorization: `Bearer ${process.env.INBOX_API_TOKEN}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        status: "Qualified",
        valuation: 12000,
        notes: "Budget confirmed for Q4. Wants a demo of the reporting API.",
      }),
    },
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`${error.code}: ${error.message} (${error.requestId})`);
  }

  return response.json();
}
```

| Field | Value |
| - | - |
| `status` | A status ID or name, or `null` |
| `notes` | Free text, or `null` |
| `valuation` | A number in the team's `currency`, or `null` |
| `assigneeId` | A member ID, or `null`. The default for the contact's threads |

A status that doesn't exist fails with `400 invalidRequest`.

## Tags

One call per tag, by ID or name. Both are idempotent.

```bash theme={null}
curl -X PUT "https://inboxapp.com/api/v2/contacts/nq2r8v5ycx1t7m4hj6kd3wzb/tags/hot-lead" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"

curl -X DELETE "https://inboxapp.com/api/v2/contacts/nq2r8v5ycx1t7m4hj6kd3wzb/tags/hot-lead" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"
```

URL-encode a name with spaces or special characters. The tag must exist: create it first with [`POST /tags`](/v2/guides/tags-and-statuses#tags).

## A contact's conversations

```bash theme={null}
curl "https://inboxapp.com/api/v2/threads?contactId=nq2r8v5ycx1t7m4hj6kd3wzb&folder=all" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"
```

## Profile fields

| Field | Notes |
| - | - |
| `username` | Without a display prefix |
| `handle` | As the platform shows it, such as `@sarahchen` |
| `verified` | A boolean. The badge kind, when there is one, is in `platformData` |
| `isOrganization` | A company or brand account |
| `followerCount`, `followingCount`, `postCount` | `null` when the platform has no such count |
| `accountStatus` | `active`, `suspended` or `notFound` |
| `platformData` | Fields only this platform has, tagged by `_tag` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.