INinstantly
LeadLabel

Create lead label

Changed on

Requires one of the following scopes: lead-labels:create, lead-labels:all, all:create, all:all

post/api/v2/lead-labels

Request

  • Base URL
    https://api.instantly.ai
  • URL
    https://api.instantly.ai/api/v2/lead-labels
  • Auth
    HTTP bearer

Request body

labelstring required

Display label for the custom lead label

interest_status_label'positive' | 'negative' | 'neutral' required

Interest status label associated with this label

descriptionstring nullable

Detailed description of the custom lead label purpose

use_with_aiboolean nullable

Whether this label should be used with AI features

Example request

{
  "label": "Hot Lead",
  "interest_status_label": "positive",
  "description": "Used for marking high-priority leads"
}

Response

The Lead Label

idstring uuid required

Unique identifier for the custom lead label

timestamp_createdstring date-time required

Timestamp when the custom lead label was created

created_bystring uuid nullable required

User ID of the creator of this label. Null when the label was created by an API key or an internal service

organization_idstring uuid required

Organization ID that owns this custom lead label

labelstring required

Display label for the custom lead label

interest_status_label'positive' | 'negative' | 'neutral' required

Interest status label associated with this label

interest_statusnumber required

Interest status associated with this label. This is generated automatically by us.

descriptionstring nullable

Detailed description of the custom lead label purpose

use_with_aiboolean nullable

Whether this label should be used with AI features

Example response

{
  "id": "01a19e6e-27a7-7555-a284-074c0d3a090e",
  "timestamp_created": "2026-11-02T22:43:01.671Z",
  "created_by": "01a19e6e-27a7-7555-a284-074db782534e",
  "organization_id": "01a19e6e-27a7-7555-a284-074e9f07f69e",
  "label": "Hot Lead",
  "interest_status_label": "positive",
  "interest_status": 1,
  "description": "Used for marking high-priority leads",
  "access_grants": [
    {
      "user_id": "01a19e6e-27a7-7555-a284-074f3964d5a2",
      "access_type": 2
    }
  ]
}

Changes

  • c781051105a8Revision changes
    • breaking

      the response property became nullable for the status

    • info

      added the optional property to the response with the status