Lead Categories

Categories are the buckets the AI sorts each lead into. Each has a name and a description that tells the AI when to use it, an optional fuDisabled flag, and its own list of follow-ups. A lead's category is stored on the contact as lead_category. Categories are addressed by name (case-insensitive).

List categories

GET/v2.0/leads/categories

Returns every category with its description, fuDisabled flag and follow-ups. meta.categorizationEnabled reports whether AI auto-categorisation is currently on.

curl -X GET "https://api.sendiee.com/v2.0/leads/categories" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": [
    {
      "name": "Hot Lead",
      "description": "Ready to buy, asked about pricing or checkout.",
      "fuDisabled": false,
      "followups": [
        {
          "delay": 600,
          "prompt": "Nudge to checkout.",
          "active": true
        }
      ]
    },
    {
      "name": "Cold Lead",
      "description": "Just browsing.",
      "fuDisabled": false,
      "followups": []
    }
  ],
  "meta": {
    "total": 2,
    "categorizationEnabled": true
  }
}

Try it — API Playground

API Key

Get a single category

GET/v2.0/leads/categories/{name}

cURL

curl -X GET "https://api.sendiee.com/v2.0/leads/categories/Hot%20Lead" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "name": "Hot Lead",
    "description": "Ready to buy.",
    "fuDisabled": false,
    "followups": []
  }
}

Create a category

POST/v2.0/leads/categories

Both name and description are required — the description is what the AI uses to decide when to apply the category.

Body

Parameter	Type	Required	Description
name	string	Required	Unique category name (case-insensitive)
description	string	Required	Tells the AI when to use this category
fuDisabled	boolean	Optional	Disable follow-ups for this category
followups	object[]	Optional	{ delay, prompt, active }[] — optional starting follow-ups

curl -X POST "https://api.sendiee.com/v2.0/leads/categories" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Hot Lead", "description": "Ready to buy, asked about pricing." }'

{
  "success": true,
  "data": {
    "name": "Hot Lead",
    "description": "Ready to buy, asked about pricing.",
    "fuDisabled": false,
    "followups": []
  }
}

{
  "error": true,
  "code": "CATEGORY_EXISTS",
  "message": "A category with this name already exists."
}

Try it — API Playground

API Key

Name*

Description*

Update / rename a category

PATCH/v2.0/leads/categories/{name}

Send a new name to rename, description to edit the AI guidance, and/or fuDisabled. The name in the URL identifies the existing category.

Renames cascade

Renaming a category relabels every contact currently in it (their lead_category is updated and a history entry is recorded).

Body

Parameter	Type	Required	Description
name	string	Optional	New name (triggers a cascading rename)
description	string	Optional	New AI guidance
fuDisabled	boolean	Optional	Toggle follow-ups for this category

cURL

curl -X PATCH "https://api.sendiee.com/v2.0/leads/categories/Hot%20Lead" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Ready to Buy", "description": "Explicitly asked to purchase." }'

{
  "success": true,
  "data": {
    "name": "Ready to Buy",
    "description": "Explicitly asked to purchase.",
    "fuDisabled": false,
    "followups": []
  }
}

Delete a category

DELETE/v2.0/leads/categories/{name}

Refuses with 409 CATEGORY_IN_USE while contacts still belong to the category, unless you pass reassignTo: an existing category name to move those contacts to, or an empty value to clear their category.

Query

Parameter	Type	Required	Description
reassignTo	string	Optional	Existing category to move in-use contacts to, or empty to clear

cURL

# Simple delete (fails if contacts still use it)
curl -X DELETE "https://api.sendiee.com/v2.0/leads/categories/Cold%20Lead" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Delete and move existing contacts to "Hot Lead"
curl -X DELETE "https://api.sendiee.com/v2.0/leads/categories/Cold%20Lead?reassignTo=Hot%20Lead" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "deleted": true,
    "reassigned": 12
  }
}

{
  "error": true,
  "code": "CATEGORY_IN_USE",
  "message": "Cannot delete: 12 contact(s) still use this category. Pass ?reassignTo= to move them first.",
  "count": 12
}