Working with contacts

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.

curl "https://inboxapp.com/api/v2/contacts?platform=twitter&platformId=1876543210987654321" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"

curl "https://inboxapp.com/api/v2/contacts?platform=twitter&username=sarahchen" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"

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

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.

Get a contact

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.

update.ts

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.

A contact’s conversations

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`

Getting started

Fundamentals

Configuration

Webhooks

Event types

Reference

Resources

Platforms

Team

Account Links

Contacts

Threads

Messages

Tags

Statuses

Colors

Events

Find a contact

Get a contact

Update a contact

Tags

A contact’s conversations

Profile fields

​Find a contact

​Get a contact

​Update a contact

​Tags

​A contact’s conversations

​Profile fields

Find a contact

Get a contact

Update a contact

Tags

A contact’s conversations

Profile fields