> ## Documentation Index
> Fetch the complete documentation index at: https://api.smartlead.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Lead Category

> Create a custom lead category for your account

<Note>
  Custom categories belong to your account only. They appear alongside the global categories in [Get Lead Categories](/api-reference/leads/categories) and can be assigned to leads like any other category.
</Note>

## Query Parameters

<ParamField query="api_key" type="string" required>
  Your SmartLead API key
</ParamField>

## Body Parameters

<ParamField body="name" type="string" required>
  Category name (max 255 characters, surrounding spaces are trimmed). Must not match an existing global or custom category name (case-insensitive).
</ParamField>

<ParamField body="sentiment_type" type="string | null">
  Sentiment of the category. Values: `positive`, `negative`, or `null` (neutral). Defaults to `null`.
</ParamField>

<ParamField body="colour_code" type="string">
  Hex colour used for the category in the app, e.g. `#4CAF50`. Defaults to `#f9f1e9`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  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']}")
  ```

  ```javascript JavaScript theme={null}
  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}`);
  }
  ```
</RequestExample>

## Response Fields

<ResponseField name="ok" type="boolean">
  `true` when the category was created
</ResponseField>

<ResponseField name="data" type="object">
  The created category

  <Expandable title="properties">
    <ResponseField name="id" type="number">
      Unique category identifier. Use it to assign the category to leads.
    </ResponseField>

    <ResponseField name="name" type="string">
      Category name
    </ResponseField>

    <ResponseField name="user_id" type="number">
      Your user ID (custom categories always have one; global categories do not)
    </ResponseField>

    <ResponseField name="sentiment_type" type="string | null">
      `positive`, `negative`, or `null` (neutral)
    </ResponseField>

    <ResponseField name="colour_code" type="string">
      Hex colour of the category
    </ResponseField>

    <ResponseField name="created_at" type="timestamp">
      ISO 8601 timestamp of when the category was created
    </ResponseField>
  </Expandable>
</ResponseField>

## Response Codes

<ResponseField name="201" type="Created">
  Category created successfully
</ResponseField>

<ResponseField name="400" type="Bad Request">
  Validation failed: missing `name`, invalid `sentiment_type`, or invalid `colour_code`
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Invalid or missing API key, or the key belongs to a client account
</ResponseField>

<ResponseField name="409" type="Conflict">
  A category with this name already exists
</ResponseField>

<ResponseField name="500" type="Internal Server Error">
  Server error occurred
</ResponseField>

<ResponseExample>
  ```json 201 - Created theme={null}
  {
    "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"
    }
  }
  ```

  ```json 400 - Validation Error theme={null}
  {
    "statusCode": 400,
    "error": "Bad Request",
    "message": "\"name\" is required"
  }
  ```

  ```json 409 - Duplicate Name theme={null}
  {
    "ok": false,
    "message": "A category with this name already exists"
  }
  ```
</ResponseExample>

## Related Endpoints

* [Get Lead Categories](/api-reference/leads/categories) - List global and custom categories
* [Update Lead Category](/api-reference/leads/update-category) - Rename or recolour a custom category
* [Delete Lead Category](/api-reference/leads/delete-category) - Remove a custom category
* [Update Lead Category in Campaign](/api-reference/campaigns/update-lead-category) - Assign a category to a lead


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