> ## 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.

# Tags and statuses

> Organize contacts with labels and pipeline stages

| | Tags | Statuses |
| - | - | - |
| A contact has | Any number | At most one |
| Use for | Labels: `hot-lead`, `partner` | Pipeline stages: `Qualified`, `Won` |
| Color | Always | Optional |

Both belong to contacts, not threads. Tagging a contact shows on every conversation with them.

## Tags

```bash theme={null}
curl -X POST "https://inboxapp.com/api/v2/tags" \
  -H "Authorization: Bearer $INBOX_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "hot-lead", "color": "red" }'
```

```json theme={null}
{ "id": "t9wq5p2bvnhfdteolyr3km7x", "name": "hot-lead", "color": "#ef4444" }
```

| Operation | Request |
| - | - |
| List | `GET /tags` |
| Create | `POST /tags` |
| Get | `GET /tags/{tagRef}` |
| Update | `PATCH /tags/{tagRef}` |
| Delete | `DELETE /tags/{tagRef}` |

Deleting a tag also removes it from every contact.

## Statuses

```bash theme={null}
curl -X POST "https://inboxapp.com/api/v2/statuses" \
  -H "Authorization: Bearer $INBOX_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Qualified", "color": "green" }'
```

The same five operations exist under `/statuses`. Set a contact's status with [`PATCH /contacts/{contactId}`](/v2/guides/contacts#update-a-contact).

## IDs or names

Anywhere a tag or status is expected, a path, a filter or a body field, you can pass its ID or its name.

* Names match ignoring case and accents: `hot-lead` finds `Hot-Lead`.
* When a value is one item's ID and another's name, the ID wins.
* Names are unique within the team. Creating a duplicate fails with `409 nameTaken`.

```bash theme={null}
curl "https://inboxapp.com/api/v2/threads?tag=hot-lead&status=Qualified" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"
```

## Colors

`color` takes a name from the palette, or a 6-digit hex value. It is stored and returned as hex.

```bash theme={null}
curl "https://inboxapp.com/api/v2/colors" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"
```

```json theme={null}
[
  { "name": "blue", "hex": "#3b82f6" },
  { "name": "red", "hex": "#ef4444" }
]
```

A tag created without a color gets a random one from the palette. A status can have `null`.

## Apply rules automatically

```typescript qualify.ts theme={null}
const API = "https://inboxapp.com/api/v2";
const headers = {
  Authorization: `Bearer ${process.env.INBOX_API_TOKEN}`,
  "Content-Type": "application/json",
};

async function tagLargeAccounts() {
  const response = await fetch(`${API}/threads?folder=inbox&expand=profile`, {
    headers,
  });

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

  const { data: threads } = await response.json();

  for (const thread of threads) {
    if ((thread.profile.followerCount ?? 0) < 10_000) continue;

    await fetch(`${API}/contacts/${thread.contactId}/tags/high-reach`, {
      method: "PUT",
      headers,
    });
  }
}
```


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