curl -X POST "https://server.smartlead.ai/api/v1/leads/categories?api_key=YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Follow Up Next Quarter",
"sentiment_type": "positive",
"colour_code": "#4CAF50"
}'
import requests
API_KEY = "YOUR_API_KEY"
response = requests.post(
"https://server.smartlead.ai/api/v1/leads/categories",
params={"api_key": API_KEY},
json={
"name": "Follow Up Next Quarter",
"sentiment_type": "positive",
"colour_code": "#4CAF50"
}
)
result = response.json()
if result.get('ok'):
print(f"Created category {result['data']['id']}")
const API_KEY = 'YOUR_API_KEY';
const response = await fetch(
`https://server.smartlead.ai/api/v1/leads/categories?api_key=${API_KEY}`,
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
name: 'Follow Up Next Quarter',
sentiment_type: 'positive',
colour_code: '#4CAF50'
})
}
);
const result = await response.json();
if (result.ok) {
console.log(`Created category ${result.data.id}`);
}
{
"ok": true,
"data": {
"id": 789,
"name": "Follow Up Next Quarter",
"user_id": 12345,
"sentiment_type": "positive",
"colour_code": "#4CAF50",
"created_at": "2025-11-20T14:22:00.000Z"
}
}
{
"statusCode": 400,
"error": "Bad Request",
"message": "\"name\" is required"
}
{
"ok": false,
"message": "A category with this name already exists"
}
Lead Categories
Create Lead Category
Create a custom lead category for your account
POST
/
api
/
v1
/
leads
/
categories
curl -X POST "https://server.smartlead.ai/api/v1/leads/categories?api_key=YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Follow Up Next Quarter",
"sentiment_type": "positive",
"colour_code": "#4CAF50"
}'
import requests
API_KEY = "YOUR_API_KEY"
response = requests.post(
"https://server.smartlead.ai/api/v1/leads/categories",
params={"api_key": API_KEY},
json={
"name": "Follow Up Next Quarter",
"sentiment_type": "positive",
"colour_code": "#4CAF50"
}
)
result = response.json()
if result.get('ok'):
print(f"Created category {result['data']['id']}")
const API_KEY = 'YOUR_API_KEY';
const response = await fetch(
`https://server.smartlead.ai/api/v1/leads/categories?api_key=${API_KEY}`,
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
name: 'Follow Up Next Quarter',
sentiment_type: 'positive',
colour_code: '#4CAF50'
})
}
);
const result = await response.json();
if (result.ok) {
console.log(`Created category ${result.data.id}`);
}
{
"ok": true,
"data": {
"id": 789,
"name": "Follow Up Next Quarter",
"user_id": 12345,
"sentiment_type": "positive",
"colour_code": "#4CAF50",
"created_at": "2025-11-20T14:22:00.000Z"
}
}
{
"statusCode": 400,
"error": "Bad Request",
"message": "\"name\" is required"
}
{
"ok": false,
"message": "A category with this name already exists"
}
Custom categories belong to your account only. They appear alongside the global categories in Get Lead Categories and can be assigned to leads like any other category.
Query Parameters
string
required
Your SmartLead API key
Body Parameters
string
required
Category name (max 255 characters, surrounding spaces are trimmed). Must not match an existing global or custom category name (case-insensitive).
string | null
Sentiment of the category. Values:
positive, negative, or null (neutral). Defaults to null.string
Hex colour used for the category in the app, e.g.
#4CAF50. Defaults to #f9f1e9.curl -X POST "https://server.smartlead.ai/api/v1/leads/categories?api_key=YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Follow Up Next Quarter",
"sentiment_type": "positive",
"colour_code": "#4CAF50"
}'
import requests
API_KEY = "YOUR_API_KEY"
response = requests.post(
"https://server.smartlead.ai/api/v1/leads/categories",
params={"api_key": API_KEY},
json={
"name": "Follow Up Next Quarter",
"sentiment_type": "positive",
"colour_code": "#4CAF50"
}
)
result = response.json()
if result.get('ok'):
print(f"Created category {result['data']['id']}")
const API_KEY = 'YOUR_API_KEY';
const response = await fetch(
`https://server.smartlead.ai/api/v1/leads/categories?api_key=${API_KEY}`,
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
name: 'Follow Up Next Quarter',
sentiment_type: 'positive',
colour_code: '#4CAF50'
})
}
);
const result = await response.json();
if (result.ok) {
console.log(`Created category ${result.data.id}`);
}
Response Fields
boolean
true when the category was createdobject
The created category
Show properties
Show properties
number
Unique category identifier. Use it to assign the category to leads.
string
Category name
number
Your user ID (custom categories always have one; global categories do not)
string | null
positive, negative, or null (neutral)string
Hex colour of the category
timestamp
ISO 8601 timestamp of when the category was created
Response Codes
Created
Category created successfully
Bad Request
Validation failed: missing
name, invalid sentiment_type, or invalid colour_codeUnauthorized
Invalid or missing API key, or the key belongs to a client account
Conflict
A category with this name already exists
Internal Server Error
Server error occurred
{
"ok": true,
"data": {
"id": 789,
"name": "Follow Up Next Quarter",
"user_id": 12345,
"sentiment_type": "positive",
"colour_code": "#4CAF50",
"created_at": "2025-11-20T14:22:00.000Z"
}
}
{
"statusCode": 400,
"error": "Bad Request",
"message": "\"name\" is required"
}
{
"ok": false,
"message": "A category with this name already exists"
}
Related Endpoints
- Get Lead Categories - List global and custom categories
- Update Lead Category - Rename or recolour a custom category
- Delete Lead Category - Remove a custom category
- Update Lead Category in Campaign - Assign a category to a lead
