> ## 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.

# Update Lead Category

> Update the name, sentiment, or colour of a custom lead category

<Warning>
  Only custom categories you created can be updated. Global (system) categories such as Interested, Not Interested, or Out Of Office are read-only and return `403`.
</Warning>

## Path Parameters

<ParamField path="category_id" type="number" required>
  The ID of the custom category to update
</ParamField>

## Query Parameters

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

## Body Parameters

Send at least one field. Only the fields you send are changed.

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

<ParamField body="sentiment_type" type="string | null">
  Values: `positive`, `negative`, or `null` (neutral)
</ParamField>

<ParamField body="colour_code" type="string">
  Hex colour, e.g. `#FFC107`
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X PATCH "https://server.smartlead.ai/api/v1/leads/categories/789?api_key=YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Follow Up In Q1",
      "sentiment_type": null,
      "colour_code": "#FFC107"
    }'
  ```

  ```python Python theme={null}
  import requests

  API_KEY = "YOUR_API_KEY"
  category_id = 789

  response = requests.patch(
      f"https://server.smartlead.ai/api/v1/leads/categories/{category_id}",
      params={"api_key": API_KEY},
      json={
          "name": "Follow Up In Q1",
          "sentiment_type": None,
          "colour_code": "#FFC107"
      }
  )

  result = response.json()
  if result.get('ok'):
      print(f"Updated category {result['data']['id']}")
  ```

  ```javascript JavaScript theme={null}
  const API_KEY = 'YOUR_API_KEY';
  const categoryId = 789;

  const response = await fetch(
    `https://server.smartlead.ai/api/v1/leads/categories/${categoryId}?api_key=${API_KEY}`,
    {
      method: 'PATCH',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        name: 'Follow Up In Q1',
        sentiment_type: null,
        colour_code: '#FFC107'
      })
    }
  );

  const result = await response.json();
  if (result.ok) {
    console.log(`Updated category ${result.data.id}`);
  }
  ```
</RequestExample>

## Response Fields

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

<ResponseField name="data" type="object">
  The updated category, with the same fields as [Create Lead Category](/api-reference/leads/create-category): `id`, `name`, `user_id`, `sentiment_type`, `colour_code`, `created_at`
</ResponseField>

## Response Codes

<ResponseField name="200" type="Success">
  Category updated successfully
</ResponseField>

<ResponseField name="400" type="Bad Request">
  Validation failed or the body was empty
</ResponseField>

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

<ResponseField name="403" type="Forbidden">
  The category is a global (system) category and cannot be modified
</ResponseField>

<ResponseField name="404" type="Not Found">
  No custom category with this ID exists in your account
</ResponseField>

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

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

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "ok": true,
    "data": {
      "id": 789,
      "name": "Follow Up In Q1",
      "user_id": 12345,
      "sentiment_type": null,
      "colour_code": "#FFC107",
      "created_at": "2025-11-20T14:22:00.000Z"
    }
  }
  ```

  ```json 403 - Global Category theme={null}
  {
    "ok": false,
    "message": "Default categories cannot be modified or deleted"
  }
  ```

  ```json 404 - Not Found theme={null}
  {
    "ok": false,
    "message": "Lead category not found"
  }
  ```

  ```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) - Find category IDs
* [Create Lead Category](/api-reference/leads/create-category) - Add a custom category
* [Delete Lead Category](/api-reference/leads/delete-category) - Remove a custom category


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