Create lead label

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

POST /api/v2/lead-labels

Create lead label

cURL

curl --request POST \
  --url https://api.instantly.ai/api/v2/lead-labels \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "label": "Hot Lead",
  "interest_status_label": "positive"
}
'

200

{
  "id": "019e3bd1-8e06-704d-a99f-98b349d77753",
  "timestamp_created": "2026-05-18T16:00:49.670Z",
  "created_by": "019e3bd1-8e06-704d-a99f-98b4d618bfcc",
  "organization_id": "019e3bd1-8e06-704d-a99f-98b5f12eaf8a",
  "label": "Hot Lead",
  "interest_status_label": "positive",
  "interest_status": 1,
  "description": "Used for marking high-priority leads",
  "use_with_ai": false
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

The Lead Label to create

The Lead Label to create

label · string · required

Display label for the custom lead label

Example:

"Hot Lead"

interest_status_label · enum<string> · required

Interest status label associated with this label

Available options: positive, negative, neutral

Example:

"positive"

description · string | null

Detailed description of the custom lead label purpose

Example:

"Used for marking high-priority leads"

use_with_ai · boolean | null

Whether this label should be used with AI features

Example:

false

Response

200

application/json

The Lead Label

A custom label for categorizing and managing leads

id · string<uuid> · required · read-only

Unique identifier for the custom lead label

Example:

"019e3bd1-8e06-704d-a99f-98b349d77753"

timestamp_created · string<date-time> · required · read-only

Timestamp when the custom lead label was created

Example:

"2026-05-18T16:00:49.670Z"

created_by · string<uuid> · required · read-only

User ID of the creator of this label

Example:

"019e3bd1-8e06-704d-a99f-98b4d618bfcc"

organization_id · string<uuid> · required · read-only

Organization ID that owns this custom lead label

Example:

"019e3bd1-8e06-704d-a99f-98b5f12eaf8a"

label · string · required

Display label for the custom lead label

Example:

"Hot Lead"

interest_status_label · enum<string> · required

Interest status label associated with this label

Available options: positive, negative, neutral

Example:

"positive"

interest_status · number · required · read-only

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

Example:

1

description · null | string

Detailed description of the custom lead label purpose

Example:

"Used for marking high-priority leads"

use_with_ai · null | boolean

Whether this label should be used with AI features

Example:

false