> ## 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 & statuses
> Organizing prospects with tags and pipeline statuses
Tags and statuses help organize prospects in your Inbox. Tags are flexible labels for categorization. Statuses represent pipeline stages.
| Feature | Tags | Statuses |
| ------------ | ------------------------ | ----------------------- |
| Per prospect | Multiple | One |
| Use case | Flexible labels | Pipeline stages |
| Example | "Hot Lead", "Enterprise" | "New → Qualified → Won" |
## Tags
### List tags
```typescript list-tags.ts theme={null}
const { data: tags } = await client.get("/tags");
console.log(`Found ${tags.length} tags`);
tags.forEach((tag) => {
console.log(`${tag.name} (${tag.color})`);
});
```
```bash cURL theme={null}
curl "https://inboxapp.com/api/v1/tags" \
-H "Authorization: Bearer $INBOX_API_TOKEN"
```
**Response:**
```json theme={null}
[
{ "id": "t8rvk2m5j0xn4wq7ybftcael", "name": "Hot Lead", "color": "#ef4444" },
{
"id": "u9swl3n6k1yo5xr8zcgudbfm",
"name": "Enterprise",
"color": "#3b82f6"
},
{ "id": "v0txm4o7l2zp6ys9adhvecgn", "name": "Partner", "color": "#22c55e" }
]
```
### Create tag
```typescript theme={null}
const { data: tag } = await client.post("/tags", {
name: "VIP",
color: "purple",
});
console.log("Created tag:", tag.id);
```
Colors accept either a **predefined name** (`"red"`, `"blue"`, `"green"`, `"purple"`, etc.) or a **hex code** (`"#ef4444"`). Use `GET /tags/colors` to see all predefined options.
### Update tag
```typescript theme={null}
const { data: tag } = await client.patch(`/tags/${tagId}`, {
name: "VIP Customer",
color: "#6366f1",
});
```
### Delete tag
```typescript theme={null}
await client.delete(`/tags/${tagId}`);
```
Deleting a tag removes it from all prospects. This cannot be undone.
### Apply tags to a prospect
Tags are updated incrementally using `addTags` and `removeTags` on the prospect context endpoint:
```typescript theme={null}
// Add tags
await client.patch(`/prospects/${prospectId}/context`, {
addTags: ["t8rvk2m5j0xn4wq7ybftcael", "u9swl3n6k1yo5xr8zcgudbfm"],
});
// Remove a tag
await client.patch(`/prospects/${prospectId}/context`, {
removeTags: ["t8rvk2m5j0xn4wq7ybftcael"],
});
// Add and remove in one request
await client.patch(`/prospects/${prospectId}/context`, {
addTags: ["v0txm4o7l2zp6ys9adhvecgn"],
removeTags: ["u9swl3n6k1yo5xr8zcgudbfm"],
});
```
There is no `tagIds` field. Tags are always modified incrementally with
`addTags` and `removeTags`.
***
## Statuses
### List statuses
```typescript list-statuses.ts theme={null}
const { data: statuses } = await client.get("/statuses");
statuses.forEach((status) => {
console.log(`${status.name} (${status.color})`);
});
```
```bash cURL theme={null}
curl "https://inboxapp.com/api/v1/statuses" \
-H "Authorization: Bearer $INBOX_API_TOKEN"
```
**Response:**
```json theme={null}
[
{
"id": "s3km7xj9wq5p2bvnhfdteoly",
"name": "New",
"color": "#64748b",
"createdAt": "2024-06-01T12:00:00.000Z"
},
{
"id": "s4ln8yk0xr6q3cw1behsifup",
"name": "Qualified",
"color": "#f59e0b",
"createdAt": "2024-06-01T12:00:00.000Z"
},
{
"id": "s5mo9zl1ys7r4dx2cfitjgvq",
"name": "Won",
"color": "#22c55e",
"createdAt": "2024-06-01T12:00:00.000Z"
}
]
```
### Create status
```typescript theme={null}
const { data: status } = await client.post("/statuses", {
name: "Demo Scheduled",
color: "teal",
});
console.log("Created status:", status.id);
```
### Update status
```typescript theme={null}
const { data: status } = await client.patch(`/statuses/${statusId}`, {
name: "Demo Complete",
color: "#14b8a6",
});
```
### Delete status
```typescript theme={null}
await client.delete(`/statuses/${statusId}`);
```
Deleting a status removes it from all prospects. This cannot be undone. The
consumer is responsible for handling any side effects — the API does not emit
individual `prospect.statusChanged` events for each affected prospect.
### Set prospect status
```typescript theme={null}
await client.patch(`/prospects/${prospectId}/context`, {
statusId: "s4ln8yk0xr6q3cw1behsifup",
});
```
### Clear prospect status
```typescript theme={null}
await client.patch(`/prospects/${prospectId}/context`, {
statusId: null,
});
```
***
## Filtering threads by tags and statuses
Filter threads using the `filters` parameter on `GET /threads`. Filters combine with AND logic:
```typescript theme={null}
const { data } = await client.get("/threads", {
params: {
inbox: "default",
"filters[tags][selectedIds][0]": "t8rvk2m5j0xn4wq7ybftcael",
"filters[statuses][selectedIds][0]": "s4ln8yk0xr6q3cw1behsifup",
"filters[assignees][noAssignee]": true,
},
});
```
Use `filters[tags][noTags]: true` or `filters[statuses][noStatus]: true` to find threads with no tags or no status respectively.
See [Managing threads — Filtering](/guides/managing-threads#filtering-threads) for the full list of filter options and the [Query parameters reference](/reference/query-parameters) for encoding details.
***
## Common patterns
### Tag system setup
```typescript theme={null}
const standardTags = [
{ name: "Hot Lead", color: "red" },
{ name: "Warm Lead", color: "orange" },
{ name: "Cold Lead", color: "slate" },
{ name: "Customer", color: "green" },
{ name: "Partner", color: "blue" },
{ name: "Do Not Contact", color: "#1f2937" },
];
for (const tag of standardTags) {
try {
await client.post("/tags", tag);
console.log(`Created: ${tag.name}`);
} catch (error) {
if (error.response?.status === 409) {
console.log(`Exists: ${tag.name}`);
} else {
throw error;
}
}
}
```
### Pipeline setup
```typescript theme={null}
const pipeline = [
{ name: "New", color: "slate" },
{ name: "Contacted", color: "blue" },
{ name: "Qualified", color: "amber" },
{ name: "Demo", color: "purple" },
{ name: "Proposal", color: "pink" },
{ name: "Won", color: "green" },
{ name: "Lost", color: "red" },
];
for (const status of pipeline) {
try {
await client.post("/statuses", status);
console.log(`Created: ${status.name}`);
} catch (error) {
if (error.response?.status === 409) {
console.log(`Exists: ${status.name}`);
}
}
}
```
### Auto-tagging by follower count
```typescript theme={null}
async function autoTag(prospectId: string, followerCount: number) {
const tagsToAdd: string[] = [];
if (followerCount > 100000) tagsToAdd.push(influencerTagId);
else if (followerCount > 10000) tagsToAdd.push(highReachTagId);
if (tagsToAdd.length > 0) {
await client.patch(`/prospects/${prospectId}/context`, {
addTags: tagsToAdd,
});
}
}
```
## Related endpoints
GET /tags
POST /tags
GET /statuses
POST /statuses
PATCH /prospects/{id}/context
GET /colors