Skip to main content
Tags and statuses help organize prospects in your Inbox. Tags are flexible labels for categorization. Statuses represent pipeline stages.
FeatureTagsStatuses
Per prospectMultipleOne
Use caseFlexible labelsPipeline stages
Example”Hot Lead”, “Enterprise""New → Qualified → Won”

​
Tags

​
List tags

const { data: tags } = await client.get("/tags");

console.log(`Found ${tags.length} tags`);
tags.forEach((tag) => {
  console.log(`${tag.name} (${tag.color})`);
});
Response: 
[
  { "id": "t8rvk2m5j0xn4wq7ybftcael", "name": "Hot Lead", "color": "#ef4444" },
  {
    "id": "u9swl3n6k1yo5xr8zcgudbfm",
    "name": "Enterprise",
    "color": "#3b82f6"
  },
  { "id": "v0txm4o7l2zp6ys9adhvecgn", "name": "Partner", "color": "#22c55e" }
]

​
Create tag

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

const { data: tag } = await client.patch(`/tags/${tagId}`, {
  name: "VIP Customer",
  color: "#6366f1",
});

​
Delete tag

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: 
// 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

const { data: statuses } = await client.get("/statuses");

statuses.forEach((status) => {
  console.log(`${status.name} (${status.color})`);
});
Response: 
[
  {
    "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

const { data: status } = await client.post("/statuses", {
  name: "Demo Scheduled",
  color: "teal",
});

console.log("Created status:", status.id);

​
Update status

const { data: status } = await client.patch(`/statuses/${statusId}`, {
  name: "Demo Complete",
  color: "#14b8a6",
});

​
Delete status

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

await client.patch(`/prospects/${prospectId}/context`, {
  statusId: "s4ln8yk0xr6q3cw1behsifup",
});

​
Clear prospect status

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: 
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 for the full list of filter options and the Query parameters reference for encoding details.

​
Common patterns

​
Tag system setup

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

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

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,
    });
  }
}

List tags

GET /tags

Create tag

POST /tags

List statuses

GET /statuses

Create status

POST /statuses

Update prospect context

PATCH /prospects//context

Available colors

GET /colors