Lead

API Explorer (2.0.0)

The entire API V2 documentation is interactive and can be tested here. To the right side of every endpoint you will see a box with an example request. You can click on the "Try it" button to send a request to the server right from the docs. You will need to provide an API key by clicking the ApiKeyAuth_token blue text.

Languages
Servers
Instantly API Server
https://api.instantly.ai/
Mock server
https://developer.instantly.ai/_mock/api/v2/

Analytics

Endpoints related to analytics

Operations

Account

An email account that can be used to send campaigns

Operations

Campaign

A campaign that can be sent to a list of recipients

Operations

Email

A campaign email, a reply, a manually sent email, or any other email that's visible in the Unibox

Operations

Email Verification

A single email verification

Operations

Lead List

A list used to store leads

Operations

Inbox Placement Test

An inbox placement test

Operations

Inbox Placement Analytics

Analytics data for individual emails in inbox placement tests

Operations

Inbox Placement Blacklist & SpamAssassin Report

Report data for an inbox placement test

Operations

API Key

API Key

Operations

Account Campaign Mapping

Account Campaign Mapping

Operations

Lead

A lead entity representing an individual lead

Operations

Lead

A lead entity representing an individual lead

idstring(uuid)read-onlyrequired

Unique identifier for the lead

Example: "01959272-5d2b-7a87-a5d7-199e472e6366"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the lead was created

Example: "2025-03-14T02:18:43.371Z"
timestamp_updatedstring(date-time)read-onlyrequired

Timestamp when the lead was last updated

Example: "2025-03-14T02:18:43.371Z"
organizationstring(uuid)read-onlyrequired

Organization ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-199f18e7bfc7"
statusnumberread-onlyrequired

Status of the lead

Enum ValueDescription
1

Active

2

Paused

3

Completed

-1

Bounced

-2

Unsubscribed

-3

Skipped

Example: 1
email_open_countnumberread-onlyrequired

Number of times the email was opened

Example: 0
email_reply_countnumberread-onlyrequired

Number of times the email was replied to

Example: 0
email_click_countnumberread-onlyrequired

Number of times the email was clicked

Example: 0
company_domainstringread-onlyrequired

Company domain of the lead

Example: "example.com"
status_summaryobjectread-onlyrequired

Status summary of the lead

status_summary.​fromstring
Example: "campaign"
status_summary.​stepIDstring
Example: "01959272-5d2b-7a87-a5d7-19a16e3e6e6d"
status_summary.​timestamp_executedstring(date-time)
Example: "2025-03-14T02:18:43.371Z"
campaignstring(uuid)

Campaign ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-19a0c5e1fc64"
emailstring

Email address of the lead

Example: "example@example.com"
personalizationstring

Personalization of the lead

Example: "Hello, how are you?"
websitestring

Website of the lead

Example: "https://example.com"
last_namestring

Last name of the lead

Example: "Doe"
first_namestring

First name of the lead

Example: "John"
company_namestring

Company name of the lead

Example: "Example Inc."
phonestring

Phone number of the lead

Example: "+1234567890"
payloadobjectread-only

Lead custom variables. This object can contain any key, but the values have to be of type string, number, boolean, or null. We do NOT allow objects or arrays as values.

status_summary_subseqobjectread-only

Subsequence status summary of the lead

last_step_fromstringread-only

Source of the last step

Example: "campaign"
last_step_idstring(uuid)read-only

ID of the last step

Example: "01959272-5d2b-7a87-a5d7-19a341212045"
last_step_timestamp_executedstring(date-time)read-only

Timestamp when the last step was executed

Example: "2025-03-14T02:18:43.371Z"
email_opened_stepnumberread-only

Last email step opened by the lead

Example: 1
email_opened_variantnumberread-only

Last step variant opened by the lead

Example: 1
email_replied_stepnumberread-only

Last email step the lead has replied to

Example: 1
email_replied_variantnumberread-only

Last step variant the lead has replied to

Example: 1
email_clicked_stepnumberread-only

Last email step the lead has clicked

Example: 1
email_clicked_variantnumberread-only

Last step variant the lead has clicked

Example: 1
lt_interest_statusnumber

Lead interest status. It can be either a static value (check below), or a custom status interest value

Enum ValueDescription
0

Out of Office

1

Interested

2

Meeting Booked

3

Meeting Completed

4

Closed

-1

Not Interested

-2

Wrong Person

-3

Lost

Example: 1
subsequence_idstringread-only

ID of the subsequence

Example: "01959272-5d2b-7a87-a5d7-19a4a1eedf0d"
verification_statusnumberread-only

Verification status of the lead

Enum ValueDescription
1

Verified

11

Pending

12

Pending Verification Job

-1

Invalid

-2

Risky

-3

Catch All

-4

Job Change

Example: 1
pl_value_leadstring

Potential value of the lead

Example: "High"
timestamp_added_subsequencestring(date-time)read-only

Timestamp when the lead was added to the subsequence

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_contactstring(date-time)read-only

Timestamp of the last contact with the lead

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_openstring(date-time)read-only

Timestamp of the last email open

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_replystring(date-time)read-only

Timestamp of the last email reply

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_interest_changestring(date-time)read-only

Timestamp of the last interest status change

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_clickstring(date-time)read-only

Timestamp of the last email click

Example: "2025-03-14T02:18:43.371Z"
enrichment_statusnumberread-only

Enrichment status of the lead

Enum ValueDescription
1

Enriched

11

Pending

-1

Enrichment data not available

-2

Error

Example: 1
list_idstring(uuid)

List ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-19a53f860c5e"
last_contacted_fromstringread-only

Source of the last contact

Example: "email"
uploaded_by_userstring(uuid)read-only

ID of the user who uploaded the lead

Example: "01959272-5d2b-7a87-a5d7-19a694ff3588"
upload_methodstringread-only

Method used to upload the lead

Enum ValueDescription
manual

Manual

api

API

website-visitor

Website Visitor

Example: "manual"
assigned_tostring(uuid)

ID of the user assigned to the lead

Example: "01959272-5d2b-7a87-a5d7-19a7ec8d1ed6"
is_website_visitorbooleanread-only

Indicates if the lead is a website visitor

Example: true
timestamp_last_touchstring(date-time)read-only

Timestamp of the last touch with the lead

Example: "2025-03-14T02:18:43.371Z"
esp_codenumberread-only

ESP code associated with the lead

Enum ValueDescription
0

In Queue

1

Google

2

Microsoft

3

Zoho

9

Yahoo

10

Yandex

12

Web.de

13

Libero.it

999

Other

1000

Not Found

Example: 1
{
  "id": "01959272-5d2b-7a87-a5d7-199e472e6366",
  "timestamp_created": "2025-03-14T02:18:43.371Z",
  "timestamp_updated": "2025-03-14T02:18:43.371Z",
  "organization": "01959272-5d2b-7a87-a5d7-199f18e7bfc7",
  "campaign": "01959272-5d2b-7a87-a5d7-19a0c5e1fc64",
  "status": 1,
  "email": "example@example.com",
  "personalization": "Hello, how are you?",
  "website": "https://example.com",
  "last_name": "Doe",
  "first_name": "John",
  "company_name": "Example Inc.",
  "phone": "+1234567890",
  "email_open_count": 0,
  "email_reply_count": 0,
  "email_click_count": 0,
  "company_domain": "example.com",
  "status_summary": {
    "from": "campaign",
    "stepID": "01959272-5d2b-7a87-a5d7-19a16e3e6e6d",
    "timestamp_executed": "2025-03-14T02:18:43.371Z"
  },
  "payload": {
    "firstName": "John",
    "lastName": "Doe",
    "companyName": "Acme Corp",
    "website": "https://example.com",
    "phone": "+1234567890",
    "personalization": "Hi {{first_name}}, I noticed you work at {{company_name}}...",
    "property1": null,
    "property2": null
  },
  "status_summary_subseq": {
    "from": "campaign",
    "stepID": "01959272-5d2b-7a87-a5d7-19a2b3a9c292",
    "timestampExecuted": "2025-03-14T02:18:43.371Z"
  },
  "last_step_from": "campaign",
  "last_step_id": "01959272-5d2b-7a87-a5d7-19a341212045",
  "last_step_timestamp_executed": "2025-03-14T02:18:43.371Z",
  "email_opened_step": 1,
  "email_opened_variant": 1,
  "email_replied_step": 1,
  "email_replied_variant": 1,
  "email_clicked_step": 1,
  "email_clicked_variant": 1,
  "lt_interest_status": 1,
  "subsequence_id": "01959272-5d2b-7a87-a5d7-19a4a1eedf0d",
  "verification_status": 1,
  "pl_value_lead": "High",
  "timestamp_added_subsequence": "2025-03-14T02:18:43.371Z",
  "timestamp_last_contact": "2025-03-14T02:18:43.371Z",
  "timestamp_last_open": "2025-03-14T02:18:43.371Z",
  "timestamp_last_reply": "2025-03-14T02:18:43.371Z",
  "timestamp_last_interest_change": "2025-03-14T02:18:43.371Z",
  "timestamp_last_click": "2025-03-14T02:18:43.371Z",
  "enrichment_status": 1,
  "list_id": "01959272-5d2b-7a87-a5d7-19a53f860c5e",
  "last_contacted_from": "email",
  "uploaded_by_user": "01959272-5d2b-7a87-a5d7-19a694ff3588",
  "upload_method": "manual",
  "assigned_to": "01959272-5d2b-7a87-a5d7-19a7ec8d1ed6",
  "is_website_visitor": true,
  "timestamp_last_touch": "2025-03-14T02:18:43.371Z",
  "esp_code": 1
}

Create lead

Request

Requires one of the following scopes: leads:create, leads:all, all:create, all:all

Bodyapplication/json

The Lead to create

campaignstring(uuid)

Campaign ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-19a0c5e1fc64"
emailstring

Email address of the lead

Example: "example@example.com"
personalizationstring

Personalization of the lead

Example: "Hello, how are you?"
websitestring

Website of the lead

Example: "https://example.com"
last_namestring

Last name of the lead

Example: "Doe"
first_namestring

First name of the lead

Example: "John"
company_namestring

Company name of the lead

Example: "Example Inc."
phonestring

Phone number of the lead

Example: "+1234567890"
lt_interest_statusnumber

Lead interest status. It can be either a static value (check below), or a custom status interest value

Enum ValueDescription
0

Out of Office

1

Interested

2

Meeting Booked

3

Meeting Completed

4

Closed

-1

Not Interested

-2

Wrong Person

-3

Lost

Example: 1
pl_value_leadstring

Potential value of the lead

Example: "High"
list_idstring(uuid)

List ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-19a53f860c5e"
assigned_tostring(uuid)

ID of the user assigned to the lead

Example: "01959272-5d2b-7a87-a5d7-19a7ec8d1ed6"
skip_if_in_workspaceboolean
Example: true
skip_if_in_campaignboolean
Example: true
skip_if_in_listboolean
Example: true
blocklist_idstring(uuid)
Example: "01959272-6e98-7fd4-9b05-3cd27cf72c63"
verify_leads_for_lead_finderboolean
Example: true
verify_leads_on_importboolean
Example: true
custom_variablesobject

Custom variables can include any metadata about the lead that is relevant to the campaign, the campaign will be updated to allow all the other leads in the campaign to have the same custom variables. The custom variables will be added to the lead payload field

Example: {"past_customer":true,"has_tried_competitors":false}
curl -i -X POST \
  https://api.instantly.ai/api/v2/leads \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

The Lead

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the lead

Example: "01959272-5d2b-7a87-a5d7-199e472e6366"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the lead was created

Example: "2025-03-14T02:18:43.371Z"
timestamp_updatedstring(date-time)read-onlyrequired

Timestamp when the lead was last updated

Example: "2025-03-14T02:18:43.371Z"
organizationstring(uuid)read-onlyrequired

Organization ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-199f18e7bfc7"
statusnumberread-onlyrequired

Status of the lead

Enum ValueDescription
1

Active

2

Paused

3

Completed

-1

Bounced

-2

Unsubscribed

-3

Skipped

Example: 1
email_open_countnumberread-onlyrequired

Number of times the email was opened

Example: 0
email_reply_countnumberread-onlyrequired

Number of times the email was replied to

Example: 0
email_click_countnumberread-onlyrequired

Number of times the email was clicked

Example: 0
company_domainstringread-onlyrequired

Company domain of the lead

Example: "example.com"
status_summaryobjectread-onlyrequired

Status summary of the lead

status_summary.​fromstring
Example: "campaign"
status_summary.​stepIDstring
Example: "01959272-5d2b-7a87-a5d7-19a16e3e6e6d"
status_summary.​timestamp_executedstring(date-time)
Example: "2025-03-14T02:18:43.371Z"
campaignstring(uuid)

Campaign ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-19a0c5e1fc64"
emailstring

Email address of the lead

Example: "example@example.com"
personalizationstring

Personalization of the lead

Example: "Hello, how are you?"
websitestring

Website of the lead

Example: "https://example.com"
last_namestring

Last name of the lead

Example: "Doe"
first_namestring

First name of the lead

Example: "John"
company_namestring

Company name of the lead

Example: "Example Inc."
phonestring

Phone number of the lead

Example: "+1234567890"
payloadobjectread-only

Lead custom variables. This object can contain any key, but the values have to be of type string, number, boolean, or null. We do NOT allow objects or arrays as values.

status_summary_subseqobjectread-only

Subsequence status summary of the lead

last_step_fromstringread-only

Source of the last step

Example: "campaign"
last_step_idstring(uuid)read-only

ID of the last step

Example: "01959272-5d2b-7a87-a5d7-19a341212045"
last_step_timestamp_executedstring(date-time)read-only

Timestamp when the last step was executed

Example: "2025-03-14T02:18:43.371Z"
email_opened_stepnumberread-only

Last email step opened by the lead

Example: 1
email_opened_variantnumberread-only

Last step variant opened by the lead

Example: 1
email_replied_stepnumberread-only

Last email step the lead has replied to

Example: 1
email_replied_variantnumberread-only

Last step variant the lead has replied to

Example: 1
email_clicked_stepnumberread-only

Last email step the lead has clicked

Example: 1
email_clicked_variantnumberread-only

Last step variant the lead has clicked

Example: 1
lt_interest_statusnumber

Lead interest status. It can be either a static value (check below), or a custom status interest value

Enum ValueDescription
0

Out of Office

1

Interested

2

Meeting Booked

3

Meeting Completed

4

Closed

-1

Not Interested

-2

Wrong Person

-3

Lost

Example: 1
subsequence_idstringread-only

ID of the subsequence

Example: "01959272-5d2b-7a87-a5d7-19a4a1eedf0d"
verification_statusnumberread-only

Verification status of the lead

Enum ValueDescription
1

Verified

11

Pending

12

Pending Verification Job

-1

Invalid

-2

Risky

-3

Catch All

-4

Job Change

Example: 1
pl_value_leadstring

Potential value of the lead

Example: "High"
timestamp_added_subsequencestring(date-time)read-only

Timestamp when the lead was added to the subsequence

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_contactstring(date-time)read-only

Timestamp of the last contact with the lead

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_openstring(date-time)read-only

Timestamp of the last email open

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_replystring(date-time)read-only

Timestamp of the last email reply

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_interest_changestring(date-time)read-only

Timestamp of the last interest status change

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_clickstring(date-time)read-only

Timestamp of the last email click

Example: "2025-03-14T02:18:43.371Z"
enrichment_statusnumberread-only

Enrichment status of the lead

Enum ValueDescription
1

Enriched

11

Pending

-1

Enrichment data not available

-2

Error

Example: 1
list_idstring(uuid)

List ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-19a53f860c5e"
last_contacted_fromstringread-only

Source of the last contact

Example: "email"
uploaded_by_userstring(uuid)read-only

ID of the user who uploaded the lead

Example: "01959272-5d2b-7a87-a5d7-19a694ff3588"
upload_methodstringread-only

Method used to upload the lead

Enum ValueDescription
manual

Manual

api

API

website-visitor

Website Visitor

Example: "manual"
assigned_tostring(uuid)

ID of the user assigned to the lead

Example: "01959272-5d2b-7a87-a5d7-19a7ec8d1ed6"
is_website_visitorbooleanread-only

Indicates if the lead is a website visitor

Example: true
timestamp_last_touchstring(date-time)read-only

Timestamp of the last touch with the lead

Example: "2025-03-14T02:18:43.371Z"
esp_codenumberread-only

ESP code associated with the lead

Enum ValueDescription
0

In Queue

1

Google

2

Microsoft

3

Zoho

9

Yahoo

10

Yandex

12

Web.de

13

Libero.it

999

Other

1000

Not Found

Example: 1
Response
application/json
{
  "id": "01959272-5d2b-7a87-a5d7-199e472e6366",
  "timestamp_created": "2025-03-14T02:18:43.371Z",
  "timestamp_updated": "2025-03-14T02:18:43.371Z",
  "organization": "01959272-5d2b-7a87-a5d7-199f18e7bfc7",
  "campaign": "01959272-5d2b-7a87-a5d7-19a0c5e1fc64",
  "status": 1,
  "email": "example@example.com",
  "personalization": "Hello, how are you?",
  "website": "https://example.com",
  "last_name": "Doe",
  "first_name": "John",
  "company_name": "Example Inc.",
  "phone": "+1234567890",
  "email_open_count": 0,
  "email_reply_count": 0,
  "email_click_count": 0,
  "company_domain": "example.com",
  "status_summary": {
    "from": "campaign",
    "stepID": "01959272-5d2b-7a87-a5d7-19a16e3e6e6d",
    "timestamp_executed": "2025-03-14T02:18:43.371Z"
  },
  "payload": {
    "firstName": "John",
    "lastName": "Doe",
    "companyName": "Acme Corp",
    "website": "https://example.com",
    "phone": "+1234567890",
    "personalization": "Hi {{first_name}}, I noticed you work at {{company_name}}...",
    "property1": null,
    "property2": null
  },
  "status_summary_subseq": {
    "from": "campaign",
    "stepID": "01959272-5d2b-7a87-a5d7-19a2b3a9c292",
    "timestampExecuted": "2025-03-14T02:18:43.371Z"
  },
  "last_step_from": "campaign",
  "last_step_id": "01959272-5d2b-7a87-a5d7-19a341212045",
  "last_step_timestamp_executed": "2025-03-14T02:18:43.371Z",
  "email_opened_step": 1,
  "email_opened_variant": 1,
  "email_replied_step": 1,
  "email_replied_variant": 1,
  "email_clicked_step": 1,
  "email_clicked_variant": 1,
  "lt_interest_status": 1,
  "subsequence_id": "01959272-5d2b-7a87-a5d7-19a4a1eedf0d",
  "verification_status": 1,
  "pl_value_lead": "High",
  "timestamp_added_subsequence": "2025-03-14T02:18:43.371Z",
  "timestamp_last_contact": "2025-03-14T02:18:43.371Z",
  "timestamp_last_open": "2025-03-14T02:18:43.371Z",
  "timestamp_last_reply": "2025-03-14T02:18:43.371Z",
  "timestamp_last_interest_change": "2025-03-14T02:18:43.371Z",
  "timestamp_last_click": "2025-03-14T02:18:43.371Z",
  "enrichment_status": 1,
  "list_id": "01959272-5d2b-7a87-a5d7-19a53f860c5e",
  "last_contacted_from": "email",
  "uploaded_by_user": "01959272-5d2b-7a87-a5d7-19a694ff3588",
  "upload_method": "manual",
  "assigned_to": "01959272-5d2b-7a87-a5d7-19a7ec8d1ed6",
  "is_website_visitor": true,
  "timestamp_last_touch": "2025-03-14T02:18:43.371Z",
  "esp_code": 1
}

List leads

Request

This endpoint is a POST endpoint, instead of GET - a deviation from the REST APIs standards we’re following because of the complex arguments it accepts, which would be too hard to express through query parameters

Requires one of the following scopes: leads:read, leads:all, all:read, all:all

Bodyapplication/json
searchstring

A search string to search the leads against - can be First Name, Last Name, or Email

Example: "John Doe"
filterstring

Filter criteria for leads. For custom lead labels, use the interest_status field.

Enum ValueDescription
FILTER_VAL_CONTACTED

Filter for contacted leads

FILTER_VAL_NOT_CONTACTED

Filter for not contacted leads

FILTER_VAL_COMPLETED

Filter for completed leads

FILTER_VAL_UNSUBSCRIBED

Filter for unsubscribed leads

FILTER_VAL_ACTIVE

Filter for active leads

FILTER_LEAD_INTERESTED

Filter for interested leads

FILTER_LEAD_NOT_INTERESTED

Filter for not interested leads

FILTER_LEAD_MEETING_BOOKED

Filter for leads with meeting booked

FILTER_LEAD_MEETING_COMPLETED

Filter for leads with meeting completed

FILTER_LEAD_CLOSED

Filter for closed leads

Example: "FILTER_VAL_CONTACTED"
campaignstring(uuid)

Campaign ID to filter leads

Example: "01959272-6b00-7524-b40c-0cc8d9a36467"
list_idstring(uuid)

List ID to filter leads

Example: "01959272-6b00-7524-b40c-0cc986e87ac6"
in_campaignboolean

Whether the lead is in a campaign

Example: true
in_listboolean

Whether the lead is in a list

Example: true
idsArray of strings(uuid)

Array of lead IDs to include

queriesArray of objects
Example: [{"actionType":"email-open","values":{"occurrence-days":1}}]
excluded_idsArray of strings(uuid)

Array of lead IDs to exclude

contactsArray of strings(email)

Array of emails the leads needs to have

limitinteger[ 1 .. 100 ]

The number of items to return

Example: 10
starting_afterstring(uuid)

The ID of the last item in the previous page - used for pagination. You can use the value of the next_starting_after field from the previous response.

Example: "01956fbd-0eb1-72db-a565-82977a586084"
organization_user_idsArray of strings(uuid)

Array of organization user IDs to filter leads

smart_view_idstring(uuid)

Smart view ID to filter leads

Example: "01959272-6e99-7e75-9037-80ce08664b5d"
is_website_visitorboolean

Whether the lead is a website visitor

Example: true
distinct_contactsboolean

Whether to return distinct contacts

Example: true
enrichment_statusnumber

Enrichment status to filter leads

Enum ValueDescription
1

The lead has been successfully enriched

11

The lead is pending enrichment

-1

Enrichment data is not available for the lead

-2

An error occurred during the enrichment process

Example: 1
curl -i -X POST \
  https://api.instantly.ai/api/v2/leads/list \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

The list of Lead

Bodyapplication/json
itemsArray of objects(Lead)required
items[].​idstring(uuid)read-onlyrequired

Unique identifier for the lead

Example: "01959272-5d2b-7a87-a5d7-199e472e6366"
items[].​timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the lead was created

Example: "2025-03-14T02:18:43.371Z"
items[].​timestamp_updatedstring(date-time)read-onlyrequired

Timestamp when the lead was last updated

Example: "2025-03-14T02:18:43.371Z"
items[].​organizationstring(uuid)read-onlyrequired

Organization ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-199f18e7bfc7"
items[].​statusnumberread-onlyrequired

Status of the lead

Enum ValueDescription
1

Active

2

Paused

3

Completed

-1

Bounced

-2

Unsubscribed

-3

Skipped

Example: 1
items[].​email_open_countnumberread-onlyrequired

Number of times the email was opened

Example: 0
items[].​email_reply_countnumberread-onlyrequired

Number of times the email was replied to

Example: 0
items[].​email_click_countnumberread-onlyrequired

Number of times the email was clicked

Example: 0
items[].​company_domainstringread-onlyrequired

Company domain of the lead

Example: "example.com"
items[].​status_summaryobjectread-onlyrequired

Status summary of the lead

items[].​status_summary.​fromstring
Example: "campaign"
items[].​status_summary.​stepIDstring
Example: "01959272-5d2b-7a87-a5d7-19a16e3e6e6d"
items[].​status_summary.​timestamp_executedstring(date-time)
Example: "2025-03-14T02:18:43.371Z"
items[].​campaignstring(uuid)

Campaign ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-19a0c5e1fc64"
items[].​emailstring

Email address of the lead

Example: "example@example.com"
items[].​personalizationstring

Personalization of the lead

Example: "Hello, how are you?"
items[].​websitestring

Website of the lead

Example: "https://example.com"
items[].​last_namestring

Last name of the lead

Example: "Doe"
items[].​first_namestring

First name of the lead

Example: "John"
items[].​company_namestring

Company name of the lead

Example: "Example Inc."
items[].​phonestring

Phone number of the lead

Example: "+1234567890"
items[].​payloadobjectread-only

Lead custom variables. This object can contain any key, but the values have to be of type string, number, boolean, or null. We do NOT allow objects or arrays as values.

items[].​status_summary_subseqobjectread-only

Subsequence status summary of the lead

items[].​last_step_fromstringread-only

Source of the last step

Example: "campaign"
items[].​last_step_idstring(uuid)read-only

ID of the last step

Example: "01959272-5d2b-7a87-a5d7-19a341212045"
items[].​last_step_timestamp_executedstring(date-time)read-only

Timestamp when the last step was executed

Example: "2025-03-14T02:18:43.371Z"
items[].​email_opened_stepnumberread-only

Last email step opened by the lead

Example: 1
items[].​email_opened_variantnumberread-only

Last step variant opened by the lead

Example: 1
items[].​email_replied_stepnumberread-only

Last email step the lead has replied to

Example: 1
items[].​email_replied_variantnumberread-only

Last step variant the lead has replied to

Example: 1
items[].​email_clicked_stepnumberread-only

Last email step the lead has clicked

Example: 1
items[].​email_clicked_variantnumberread-only

Last step variant the lead has clicked

Example: 1
items[].​lt_interest_statusnumber

Lead interest status. It can be either a static value (check below), or a custom status interest value

Enum ValueDescription
0

Out of Office

1

Interested

2

Meeting Booked

3

Meeting Completed

4

Closed

-1

Not Interested

-2

Wrong Person

-3

Lost

Example: 1
items[].​subsequence_idstringread-only

ID of the subsequence

Example: "01959272-5d2b-7a87-a5d7-19a4a1eedf0d"
items[].​verification_statusnumberread-only

Verification status of the lead

Enum ValueDescription
1

Verified

11

Pending

12

Pending Verification Job

-1

Invalid

-2

Risky

-3

Catch All

-4

Job Change

Example: 1
items[].​pl_value_leadstring

Potential value of the lead

Example: "High"
items[].​timestamp_added_subsequencestring(date-time)read-only

Timestamp when the lead was added to the subsequence

Example: "2025-03-14T02:18:43.371Z"
items[].​timestamp_last_contactstring(date-time)read-only

Timestamp of the last contact with the lead

Example: "2025-03-14T02:18:43.371Z"
items[].​timestamp_last_openstring(date-time)read-only

Timestamp of the last email open

Example: "2025-03-14T02:18:43.371Z"
items[].​timestamp_last_replystring(date-time)read-only

Timestamp of the last email reply

Example: "2025-03-14T02:18:43.371Z"
items[].​timestamp_last_interest_changestring(date-time)read-only

Timestamp of the last interest status change

Example: "2025-03-14T02:18:43.371Z"
items[].​timestamp_last_clickstring(date-time)read-only

Timestamp of the last email click

Example: "2025-03-14T02:18:43.371Z"
items[].​enrichment_statusnumberread-only

Enrichment status of the lead

Enum ValueDescription
1

Enriched

11

Pending

-1

Enrichment data not available

-2

Error

Example: 1
items[].​list_idstring(uuid)

List ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-19a53f860c5e"
items[].​last_contacted_fromstringread-only

Source of the last contact

Example: "email"
items[].​uploaded_by_userstring(uuid)read-only

ID of the user who uploaded the lead

Example: "01959272-5d2b-7a87-a5d7-19a694ff3588"
items[].​upload_methodstringread-only

Method used to upload the lead

Enum ValueDescription
manual

Manual

api

API

website-visitor

Website Visitor

Example: "manual"
items[].​assigned_tostring(uuid)

ID of the user assigned to the lead

Example: "01959272-5d2b-7a87-a5d7-19a7ec8d1ed6"
items[].​is_website_visitorbooleanread-only

Indicates if the lead is a website visitor

Example: true
items[].​timestamp_last_touchstring(date-time)read-only

Timestamp of the last touch with the lead

Example: "2025-03-14T02:18:43.371Z"
items[].​esp_codenumberread-only

ESP code associated with the lead

Enum ValueDescription
0

In Queue

1

Google

2

Microsoft

3

Zoho

9

Yahoo

10

Yandex

12

Web.de

13

Libero.it

999

Other

1000

Not Found

Example: 1
next_starting_afterstring

The filter for getting the next items after this one, this could either be a UUID, a MongoDB ID, a timestamp, on an email depending on the specific API

Example: "0000-0000-0000-0000"
Response
application/json
{
  "items": [
    { … }
  ],
  "next_starting_after": "0000-0000-0000-0000"
}

Get lead

Request

Requires one of the following scopes: leads:read, leads:all, all:read, all:all

Path
idstringrequired
curl -i -X GET \
  'https://api.instantly.ai/api/v2/leads/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The requested Lead

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the lead

Example: "01959272-5d2b-7a87-a5d7-199e472e6366"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the lead was created

Example: "2025-03-14T02:18:43.371Z"
timestamp_updatedstring(date-time)read-onlyrequired

Timestamp when the lead was last updated

Example: "2025-03-14T02:18:43.371Z"
organizationstring(uuid)read-onlyrequired

Organization ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-199f18e7bfc7"
statusnumberread-onlyrequired

Status of the lead

Enum ValueDescription
1

Active

2

Paused

3

Completed

-1

Bounced

-2

Unsubscribed

-3

Skipped

Example: 1
email_open_countnumberread-onlyrequired

Number of times the email was opened

Example: 0
email_reply_countnumberread-onlyrequired

Number of times the email was replied to

Example: 0
email_click_countnumberread-onlyrequired

Number of times the email was clicked

Example: 0
company_domainstringread-onlyrequired

Company domain of the lead

Example: "example.com"
status_summaryobjectread-onlyrequired

Status summary of the lead

status_summary.​fromstring
Example: "campaign"
status_summary.​stepIDstring
Example: "01959272-5d2b-7a87-a5d7-19a16e3e6e6d"
status_summary.​timestamp_executedstring(date-time)
Example: "2025-03-14T02:18:43.371Z"
campaignstring(uuid)

Campaign ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-19a0c5e1fc64"
emailstring

Email address of the lead

Example: "example@example.com"
personalizationstring

Personalization of the lead

Example: "Hello, how are you?"
websitestring

Website of the lead

Example: "https://example.com"
last_namestring

Last name of the lead

Example: "Doe"
first_namestring

First name of the lead

Example: "John"
company_namestring

Company name of the lead

Example: "Example Inc."
phonestring

Phone number of the lead

Example: "+1234567890"
payloadobjectread-only

Lead custom variables. This object can contain any key, but the values have to be of type string, number, boolean, or null. We do NOT allow objects or arrays as values.

status_summary_subseqobjectread-only

Subsequence status summary of the lead

last_step_fromstringread-only

Source of the last step

Example: "campaign"
last_step_idstring(uuid)read-only

ID of the last step

Example: "01959272-5d2b-7a87-a5d7-19a341212045"
last_step_timestamp_executedstring(date-time)read-only

Timestamp when the last step was executed

Example: "2025-03-14T02:18:43.371Z"
email_opened_stepnumberread-only

Last email step opened by the lead

Example: 1
email_opened_variantnumberread-only

Last step variant opened by the lead

Example: 1
email_replied_stepnumberread-only

Last email step the lead has replied to

Example: 1
email_replied_variantnumberread-only

Last step variant the lead has replied to

Example: 1
email_clicked_stepnumberread-only

Last email step the lead has clicked

Example: 1
email_clicked_variantnumberread-only

Last step variant the lead has clicked

Example: 1
lt_interest_statusnumber

Lead interest status. It can be either a static value (check below), or a custom status interest value

Enum ValueDescription
0

Out of Office

1

Interested

2

Meeting Booked

3

Meeting Completed

4

Closed

-1

Not Interested

-2

Wrong Person

-3

Lost

Example: 1
subsequence_idstringread-only

ID of the subsequence

Example: "01959272-5d2b-7a87-a5d7-19a4a1eedf0d"
verification_statusnumberread-only

Verification status of the lead

Enum ValueDescription
1

Verified

11

Pending

12

Pending Verification Job

-1

Invalid

-2

Risky

-3

Catch All

-4

Job Change

Example: 1
pl_value_leadstring

Potential value of the lead

Example: "High"
timestamp_added_subsequencestring(date-time)read-only

Timestamp when the lead was added to the subsequence

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_contactstring(date-time)read-only

Timestamp of the last contact with the lead

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_openstring(date-time)read-only

Timestamp of the last email open

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_replystring(date-time)read-only

Timestamp of the last email reply

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_interest_changestring(date-time)read-only

Timestamp of the last interest status change

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_clickstring(date-time)read-only

Timestamp of the last email click

Example: "2025-03-14T02:18:43.371Z"
enrichment_statusnumberread-only

Enrichment status of the lead

Enum ValueDescription
1

Enriched

11

Pending

-1

Enrichment data not available

-2

Error

Example: 1
list_idstring(uuid)

List ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-19a53f860c5e"
last_contacted_fromstringread-only

Source of the last contact

Example: "email"
uploaded_by_userstring(uuid)read-only

ID of the user who uploaded the lead

Example: "01959272-5d2b-7a87-a5d7-19a694ff3588"
upload_methodstringread-only

Method used to upload the lead

Enum ValueDescription
manual

Manual

api

API

website-visitor

Website Visitor

Example: "manual"
assigned_tostring(uuid)

ID of the user assigned to the lead

Example: "01959272-5d2b-7a87-a5d7-19a7ec8d1ed6"
is_website_visitorbooleanread-only

Indicates if the lead is a website visitor

Example: true
timestamp_last_touchstring(date-time)read-only

Timestamp of the last touch with the lead

Example: "2025-03-14T02:18:43.371Z"
esp_codenumberread-only

ESP code associated with the lead

Enum ValueDescription
0

In Queue

1

Google

2

Microsoft

3

Zoho

9

Yahoo

10

Yandex

12

Web.de

13

Libero.it

999

Other

1000

Not Found

Example: 1
Response
application/json
{
  "id": "01959272-5d2b-7a87-a5d7-199e472e6366",
  "timestamp_created": "2025-03-14T02:18:43.371Z",
  "timestamp_updated": "2025-03-14T02:18:43.371Z",
  "organization": "01959272-5d2b-7a87-a5d7-199f18e7bfc7",
  "campaign": "01959272-5d2b-7a87-a5d7-19a0c5e1fc64",
  "status": 1,
  "email": "example@example.com",
  "personalization": "Hello, how are you?",
  "website": "https://example.com",
  "last_name": "Doe",
  "first_name": "John",
  "company_name": "Example Inc.",
  "phone": "+1234567890",
  "email_open_count": 0,
  "email_reply_count": 0,
  "email_click_count": 0,
  "company_domain": "example.com",
  "status_summary": {
    "from": "campaign",
    "stepID": "01959272-5d2b-7a87-a5d7-19a16e3e6e6d",
    "timestamp_executed": "2025-03-14T02:18:43.371Z"
  },
  "payload": {
    "firstName": "John",
    "lastName": "Doe",
    "companyName": "Acme Corp",
    "website": "https://example.com",
    "phone": "+1234567890",
    "personalization": "Hi {{first_name}}, I noticed you work at {{company_name}}...",
    "property1": null,
    "property2": null
  },
  "status_summary_subseq": {
    "from": "campaign",
    "stepID": "01959272-5d2b-7a87-a5d7-19a2b3a9c292",
    "timestampExecuted": "2025-03-14T02:18:43.371Z"
  },
  "last_step_from": "campaign",
  "last_step_id": "01959272-5d2b-7a87-a5d7-19a341212045",
  "last_step_timestamp_executed": "2025-03-14T02:18:43.371Z",
  "email_opened_step": 1,
  "email_opened_variant": 1,
  "email_replied_step": 1,
  "email_replied_variant": 1,
  "email_clicked_step": 1,
  "email_clicked_variant": 1,
  "lt_interest_status": 1,
  "subsequence_id": "01959272-5d2b-7a87-a5d7-19a4a1eedf0d",
  "verification_status": 1,
  "pl_value_lead": "High",
  "timestamp_added_subsequence": "2025-03-14T02:18:43.371Z",
  "timestamp_last_contact": "2025-03-14T02:18:43.371Z",
  "timestamp_last_open": "2025-03-14T02:18:43.371Z",
  "timestamp_last_reply": "2025-03-14T02:18:43.371Z",
  "timestamp_last_interest_change": "2025-03-14T02:18:43.371Z",
  "timestamp_last_click": "2025-03-14T02:18:43.371Z",
  "enrichment_status": 1,
  "list_id": "01959272-5d2b-7a87-a5d7-19a53f860c5e",
  "last_contacted_from": "email",
  "uploaded_by_user": "01959272-5d2b-7a87-a5d7-19a694ff3588",
  "upload_method": "manual",
  "assigned_to": "01959272-5d2b-7a87-a5d7-19a7ec8d1ed6",
  "is_website_visitor": true,
  "timestamp_last_touch": "2025-03-14T02:18:43.371Z",
  "esp_code": 1
}

Patch lead

Request

Requires one of the following scopes: leads:update, leads:all, all:update, all:all

Path
idstringrequired
Bodyapplication/json
non-empty
personalizationstring

Personalization of the lead

Example: "Hello, how are you?"
websitestring

Website of the lead

Example: "https://example.com"
last_namestring

Last name of the lead

Example: "Doe"
first_namestring

First name of the lead

Example: "John"
company_namestring

Company name of the lead

Example: "Example Inc."
phonestring

Phone number of the lead

Example: "+1234567890"
lt_interest_statusnumber

Lead interest status. It can be either a static value (check below), or a custom status interest value

Enum ValueDescription
0

Out of Office

1

Interested

2

Meeting Booked

3

Meeting Completed

4

Closed

-1

Not Interested

-2

Wrong Person

-3

Lost

Example: 1
pl_value_leadstring

Potential value of the lead

Example: "High"
assigned_tostring(uuid)

ID of the user assigned to the lead

Example: "01959272-5d2b-7a87-a5d7-19a7ec8d1ed6"
custom_variablesobject

Custom variables can include any metadata about the lead that is relevant to the campaign, the campaign will be updated to allow all the other leads in the campaign to have the same custom variables. The custom variables will be added to the lead payload field

Example: {"past_customer":true,"has_tried_competitors":false}
curl -i -X PATCH \
  'https://api.instantly.ai/api/v2/leads/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

The updated Lead

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the lead

Example: "01959272-5d2b-7a87-a5d7-199e472e6366"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the lead was created

Example: "2025-03-14T02:18:43.371Z"
timestamp_updatedstring(date-time)read-onlyrequired

Timestamp when the lead was last updated

Example: "2025-03-14T02:18:43.371Z"
organizationstring(uuid)read-onlyrequired

Organization ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-199f18e7bfc7"
statusnumberread-onlyrequired

Status of the lead

Enum ValueDescription
1

Active

2

Paused

3

Completed

-1

Bounced

-2

Unsubscribed

-3

Skipped

Example: 1
email_open_countnumberread-onlyrequired

Number of times the email was opened

Example: 0
email_reply_countnumberread-onlyrequired

Number of times the email was replied to

Example: 0
email_click_countnumberread-onlyrequired

Number of times the email was clicked

Example: 0
company_domainstringread-onlyrequired

Company domain of the lead

Example: "example.com"
status_summaryobjectread-onlyrequired

Status summary of the lead

status_summary.​fromstring
Example: "campaign"
status_summary.​stepIDstring
Example: "01959272-5d2b-7a87-a5d7-19a16e3e6e6d"
status_summary.​timestamp_executedstring(date-time)
Example: "2025-03-14T02:18:43.371Z"
campaignstring(uuid)

Campaign ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-19a0c5e1fc64"
emailstring

Email address of the lead

Example: "example@example.com"
personalizationstring

Personalization of the lead

Example: "Hello, how are you?"
websitestring

Website of the lead

Example: "https://example.com"
last_namestring

Last name of the lead

Example: "Doe"
first_namestring

First name of the lead

Example: "John"
company_namestring

Company name of the lead

Example: "Example Inc."
phonestring

Phone number of the lead

Example: "+1234567890"
payloadobjectread-only

Lead custom variables. This object can contain any key, but the values have to be of type string, number, boolean, or null. We do NOT allow objects or arrays as values.

status_summary_subseqobjectread-only

Subsequence status summary of the lead

last_step_fromstringread-only

Source of the last step

Example: "campaign"
last_step_idstring(uuid)read-only

ID of the last step

Example: "01959272-5d2b-7a87-a5d7-19a341212045"
last_step_timestamp_executedstring(date-time)read-only

Timestamp when the last step was executed

Example: "2025-03-14T02:18:43.371Z"
email_opened_stepnumberread-only

Last email step opened by the lead

Example: 1
email_opened_variantnumberread-only

Last step variant opened by the lead

Example: 1
email_replied_stepnumberread-only

Last email step the lead has replied to

Example: 1
email_replied_variantnumberread-only

Last step variant the lead has replied to

Example: 1
email_clicked_stepnumberread-only

Last email step the lead has clicked

Example: 1
email_clicked_variantnumberread-only

Last step variant the lead has clicked

Example: 1
lt_interest_statusnumber

Lead interest status. It can be either a static value (check below), or a custom status interest value

Enum ValueDescription
0

Out of Office

1

Interested

2

Meeting Booked

3

Meeting Completed

4

Closed

-1

Not Interested

-2

Wrong Person

-3

Lost

Example: 1
subsequence_idstringread-only

ID of the subsequence

Example: "01959272-5d2b-7a87-a5d7-19a4a1eedf0d"
verification_statusnumberread-only

Verification status of the lead

Enum ValueDescription
1

Verified

11

Pending

12

Pending Verification Job

-1

Invalid

-2

Risky

-3

Catch All

-4

Job Change

Example: 1
pl_value_leadstring

Potential value of the lead

Example: "High"
timestamp_added_subsequencestring(date-time)read-only

Timestamp when the lead was added to the subsequence

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_contactstring(date-time)read-only

Timestamp of the last contact with the lead

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_openstring(date-time)read-only

Timestamp of the last email open

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_replystring(date-time)read-only

Timestamp of the last email reply

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_interest_changestring(date-time)read-only

Timestamp of the last interest status change

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_clickstring(date-time)read-only

Timestamp of the last email click

Example: "2025-03-14T02:18:43.371Z"
enrichment_statusnumberread-only

Enrichment status of the lead

Enum ValueDescription
1

Enriched

11

Pending

-1

Enrichment data not available

-2

Error

Example: 1
list_idstring(uuid)

List ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-19a53f860c5e"
last_contacted_fromstringread-only

Source of the last contact

Example: "email"
uploaded_by_userstring(uuid)read-only

ID of the user who uploaded the lead

Example: "01959272-5d2b-7a87-a5d7-19a694ff3588"
upload_methodstringread-only

Method used to upload the lead

Enum ValueDescription
manual

Manual

api

API

website-visitor

Website Visitor

Example: "manual"
assigned_tostring(uuid)

ID of the user assigned to the lead

Example: "01959272-5d2b-7a87-a5d7-19a7ec8d1ed6"
is_website_visitorbooleanread-only

Indicates if the lead is a website visitor

Example: true
timestamp_last_touchstring(date-time)read-only

Timestamp of the last touch with the lead

Example: "2025-03-14T02:18:43.371Z"
esp_codenumberread-only

ESP code associated with the lead

Enum ValueDescription
0

In Queue

1

Google

2

Microsoft

3

Zoho

9

Yahoo

10

Yandex

12

Web.de

13

Libero.it

999

Other

1000

Not Found

Example: 1
Response
application/json
{
  "id": "01959272-5d2b-7a87-a5d7-199e472e6366",
  "timestamp_created": "2025-03-14T02:18:43.371Z",
  "timestamp_updated": "2025-03-14T02:18:43.371Z",
  "organization": "01959272-5d2b-7a87-a5d7-199f18e7bfc7",
  "campaign": "01959272-5d2b-7a87-a5d7-19a0c5e1fc64",
  "status": 1,
  "email": "example@example.com",
  "personalization": "Hello, how are you?",
  "website": "https://example.com",
  "last_name": "Doe",
  "first_name": "John",
  "company_name": "Example Inc.",
  "phone": "+1234567890",
  "email_open_count": 0,
  "email_reply_count": 0,
  "email_click_count": 0,
  "company_domain": "example.com",
  "status_summary": {
    "from": "campaign",
    "stepID": "01959272-5d2b-7a87-a5d7-19a16e3e6e6d",
    "timestamp_executed": "2025-03-14T02:18:43.371Z"
  },
  "payload": {
    "firstName": "John",
    "lastName": "Doe",
    "companyName": "Acme Corp",
    "website": "https://example.com",
    "phone": "+1234567890",
    "personalization": "Hi {{first_name}}, I noticed you work at {{company_name}}...",
    "property1": null,
    "property2": null
  },
  "status_summary_subseq": {
    "from": "campaign",
    "stepID": "01959272-5d2b-7a87-a5d7-19a2b3a9c292",
    "timestampExecuted": "2025-03-14T02:18:43.371Z"
  },
  "last_step_from": "campaign",
  "last_step_id": "01959272-5d2b-7a87-a5d7-19a341212045",
  "last_step_timestamp_executed": "2025-03-14T02:18:43.371Z",
  "email_opened_step": 1,
  "email_opened_variant": 1,
  "email_replied_step": 1,
  "email_replied_variant": 1,
  "email_clicked_step": 1,
  "email_clicked_variant": 1,
  "lt_interest_status": 1,
  "subsequence_id": "01959272-5d2b-7a87-a5d7-19a4a1eedf0d",
  "verification_status": 1,
  "pl_value_lead": "High",
  "timestamp_added_subsequence": "2025-03-14T02:18:43.371Z",
  "timestamp_last_contact": "2025-03-14T02:18:43.371Z",
  "timestamp_last_open": "2025-03-14T02:18:43.371Z",
  "timestamp_last_reply": "2025-03-14T02:18:43.371Z",
  "timestamp_last_interest_change": "2025-03-14T02:18:43.371Z",
  "timestamp_last_click": "2025-03-14T02:18:43.371Z",
  "enrichment_status": 1,
  "list_id": "01959272-5d2b-7a87-a5d7-19a53f860c5e",
  "last_contacted_from": "email",
  "uploaded_by_user": "01959272-5d2b-7a87-a5d7-19a694ff3588",
  "upload_method": "manual",
  "assigned_to": "01959272-5d2b-7a87-a5d7-19a7ec8d1ed6",
  "is_website_visitor": true,
  "timestamp_last_touch": "2025-03-14T02:18:43.371Z",
  "esp_code": 1
}

Delete lead

Request

Requires one of the following scopes: leads:delete, leads:all, all:delete, all:all

Path
idstringrequired
curl -i -X DELETE \
  'https://api.instantly.ai/api/v2/leads/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The deleted Lead

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the lead

Example: "01959272-5d2b-7a87-a5d7-199e472e6366"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the lead was created

Example: "2025-03-14T02:18:43.371Z"
timestamp_updatedstring(date-time)read-onlyrequired

Timestamp when the lead was last updated

Example: "2025-03-14T02:18:43.371Z"
organizationstring(uuid)read-onlyrequired

Organization ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-199f18e7bfc7"
statusnumberread-onlyrequired

Status of the lead

Enum ValueDescription
1

Active

2

Paused

3

Completed

-1

Bounced

-2

Unsubscribed

-3

Skipped

Example: 1
email_open_countnumberread-onlyrequired

Number of times the email was opened

Example: 0
email_reply_countnumberread-onlyrequired

Number of times the email was replied to

Example: 0
email_click_countnumberread-onlyrequired

Number of times the email was clicked

Example: 0
company_domainstringread-onlyrequired

Company domain of the lead

Example: "example.com"
status_summaryobjectread-onlyrequired

Status summary of the lead

status_summary.​fromstring
Example: "campaign"
status_summary.​stepIDstring
Example: "01959272-5d2b-7a87-a5d7-19a16e3e6e6d"
status_summary.​timestamp_executedstring(date-time)
Example: "2025-03-14T02:18:43.371Z"
campaignstring(uuid)

Campaign ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-19a0c5e1fc64"
emailstring

Email address of the lead

Example: "example@example.com"
personalizationstring

Personalization of the lead

Example: "Hello, how are you?"
websitestring

Website of the lead

Example: "https://example.com"
last_namestring

Last name of the lead

Example: "Doe"
first_namestring

First name of the lead

Example: "John"
company_namestring

Company name of the lead

Example: "Example Inc."
phonestring

Phone number of the lead

Example: "+1234567890"
payloadobjectread-only

Lead custom variables. This object can contain any key, but the values have to be of type string, number, boolean, or null. We do NOT allow objects or arrays as values.

status_summary_subseqobjectread-only

Subsequence status summary of the lead

last_step_fromstringread-only

Source of the last step

Example: "campaign"
last_step_idstring(uuid)read-only

ID of the last step

Example: "01959272-5d2b-7a87-a5d7-19a341212045"
last_step_timestamp_executedstring(date-time)read-only

Timestamp when the last step was executed

Example: "2025-03-14T02:18:43.371Z"
email_opened_stepnumberread-only

Last email step opened by the lead

Example: 1
email_opened_variantnumberread-only

Last step variant opened by the lead

Example: 1
email_replied_stepnumberread-only

Last email step the lead has replied to

Example: 1
email_replied_variantnumberread-only

Last step variant the lead has replied to

Example: 1
email_clicked_stepnumberread-only

Last email step the lead has clicked

Example: 1
email_clicked_variantnumberread-only

Last step variant the lead has clicked

Example: 1
lt_interest_statusnumber

Lead interest status. It can be either a static value (check below), or a custom status interest value

Enum ValueDescription
0

Out of Office

1

Interested

2

Meeting Booked

3

Meeting Completed

4

Closed

-1

Not Interested

-2

Wrong Person

-3

Lost

Example: 1
subsequence_idstringread-only

ID of the subsequence

Example: "01959272-5d2b-7a87-a5d7-19a4a1eedf0d"
verification_statusnumberread-only

Verification status of the lead

Enum ValueDescription
1

Verified

11

Pending

12

Pending Verification Job

-1

Invalid

-2

Risky

-3

Catch All

-4

Job Change

Example: 1
pl_value_leadstring

Potential value of the lead

Example: "High"
timestamp_added_subsequencestring(date-time)read-only

Timestamp when the lead was added to the subsequence

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_contactstring(date-time)read-only

Timestamp of the last contact with the lead

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_openstring(date-time)read-only

Timestamp of the last email open

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_replystring(date-time)read-only

Timestamp of the last email reply

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_interest_changestring(date-time)read-only

Timestamp of the last interest status change

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_clickstring(date-time)read-only

Timestamp of the last email click

Example: "2025-03-14T02:18:43.371Z"
enrichment_statusnumberread-only

Enrichment status of the lead

Enum ValueDescription
1

Enriched

11

Pending

-1

Enrichment data not available

-2

Error

Example: 1
list_idstring(uuid)

List ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-19a53f860c5e"
last_contacted_fromstringread-only

Source of the last contact

Example: "email"
uploaded_by_userstring(uuid)read-only

ID of the user who uploaded the lead

Example: "01959272-5d2b-7a87-a5d7-19a694ff3588"
upload_methodstringread-only

Method used to upload the lead

Enum ValueDescription
manual

Manual

api

API

website-visitor

Website Visitor

Example: "manual"
assigned_tostring(uuid)

ID of the user assigned to the lead

Example: "01959272-5d2b-7a87-a5d7-19a7ec8d1ed6"
is_website_visitorbooleanread-only

Indicates if the lead is a website visitor

Example: true
timestamp_last_touchstring(date-time)read-only

Timestamp of the last touch with the lead

Example: "2025-03-14T02:18:43.371Z"
esp_codenumberread-only

ESP code associated with the lead

Enum ValueDescription
0

In Queue

1

Google

2

Microsoft

3

Zoho

9

Yahoo

10

Yandex

12

Web.de

13

Libero.it

999

Other

1000

Not Found

Example: 1
Response
application/json
{
  "id": "01959272-5d2b-7a87-a5d7-199e472e6366",
  "timestamp_created": "2025-03-14T02:18:43.371Z",
  "timestamp_updated": "2025-03-14T02:18:43.371Z",
  "organization": "01959272-5d2b-7a87-a5d7-199f18e7bfc7",
  "campaign": "01959272-5d2b-7a87-a5d7-19a0c5e1fc64",
  "status": 1,
  "email": "example@example.com",
  "personalization": "Hello, how are you?",
  "website": "https://example.com",
  "last_name": "Doe",
  "first_name": "John",
  "company_name": "Example Inc.",
  "phone": "+1234567890",
  "email_open_count": 0,
  "email_reply_count": 0,
  "email_click_count": 0,
  "company_domain": "example.com",
  "status_summary": {
    "from": "campaign",
    "stepID": "01959272-5d2b-7a87-a5d7-19a16e3e6e6d",
    "timestamp_executed": "2025-03-14T02:18:43.371Z"
  },
  "payload": {
    "firstName": "John",
    "lastName": "Doe",
    "companyName": "Acme Corp",
    "website": "https://example.com",
    "phone": "+1234567890",
    "personalization": "Hi {{first_name}}, I noticed you work at {{company_name}}...",
    "property1": null,
    "property2": null
  },
  "status_summary_subseq": {
    "from": "campaign",
    "stepID": "01959272-5d2b-7a87-a5d7-19a2b3a9c292",
    "timestampExecuted": "2025-03-14T02:18:43.371Z"
  },
  "last_step_from": "campaign",
  "last_step_id": "01959272-5d2b-7a87-a5d7-19a341212045",
  "last_step_timestamp_executed": "2025-03-14T02:18:43.371Z",
  "email_opened_step": 1,
  "email_opened_variant": 1,
  "email_replied_step": 1,
  "email_replied_variant": 1,
  "email_clicked_step": 1,
  "email_clicked_variant": 1,
  "lt_interest_status": 1,
  "subsequence_id": "01959272-5d2b-7a87-a5d7-19a4a1eedf0d",
  "verification_status": 1,
  "pl_value_lead": "High",
  "timestamp_added_subsequence": "2025-03-14T02:18:43.371Z",
  "timestamp_last_contact": "2025-03-14T02:18:43.371Z",
  "timestamp_last_open": "2025-03-14T02:18:43.371Z",
  "timestamp_last_reply": "2025-03-14T02:18:43.371Z",
  "timestamp_last_interest_change": "2025-03-14T02:18:43.371Z",
  "timestamp_last_click": "2025-03-14T02:18:43.371Z",
  "enrichment_status": 1,
  "list_id": "01959272-5d2b-7a87-a5d7-19a53f860c5e",
  "last_contacted_from": "email",
  "uploaded_by_user": "01959272-5d2b-7a87-a5d7-19a694ff3588",
  "upload_method": "manual",
  "assigned_to": "01959272-5d2b-7a87-a5d7-19a7ec8d1ed6",
  "is_website_visitor": true,
  "timestamp_last_touch": "2025-03-14T02:18:43.371Z",
  "esp_code": 1
}

Merge two leads

Request

Merge two leads

Requires one of the following scopes: leads:update, leads:all, all:update, all:all

Bodyapplication/jsonrequired
lead_idstring(uuid)required
Example: "01959272-6e99-7e75-9037-80cf2a33c794"
destination_lead_idstring(uuid)required
Example: "01959272-6e99-7e75-9037-80d09714ef7e"
curl -i -X POST \
  https://api.instantly.ai/api/v2/leads/merge \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "lead_id": "01959272-6e99-7e75-9037-80cf2a33c794",
    "destination_lead_id": "01959272-6e99-7e75-9037-80d09714ef7e"
  }'

Responses

The requested Lead

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the lead

Example: "01959272-5d2b-7a87-a5d7-199e472e6366"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the lead was created

Example: "2025-03-14T02:18:43.371Z"
timestamp_updatedstring(date-time)read-onlyrequired

Timestamp when the lead was last updated

Example: "2025-03-14T02:18:43.371Z"
organizationstring(uuid)read-onlyrequired

Organization ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-199f18e7bfc7"
statusnumberread-onlyrequired

Status of the lead

Enum ValueDescription
1

Active

2

Paused

3

Completed

-1

Bounced

-2

Unsubscribed

-3

Skipped

Example: 1
email_open_countnumberread-onlyrequired

Number of times the email was opened

Example: 0
email_reply_countnumberread-onlyrequired

Number of times the email was replied to

Example: 0
email_click_countnumberread-onlyrequired

Number of times the email was clicked

Example: 0
company_domainstringread-onlyrequired

Company domain of the lead

Example: "example.com"
status_summaryobjectread-onlyrequired

Status summary of the lead

status_summary.​fromstring
Example: "campaign"
status_summary.​stepIDstring
Example: "01959272-5d2b-7a87-a5d7-19a16e3e6e6d"
status_summary.​timestamp_executedstring(date-time)
Example: "2025-03-14T02:18:43.371Z"
campaignstring(uuid)

Campaign ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-19a0c5e1fc64"
emailstring

Email address of the lead

Example: "example@example.com"
personalizationstring

Personalization of the lead

Example: "Hello, how are you?"
websitestring

Website of the lead

Example: "https://example.com"
last_namestring

Last name of the lead

Example: "Doe"
first_namestring

First name of the lead

Example: "John"
company_namestring

Company name of the lead

Example: "Example Inc."
phonestring

Phone number of the lead

Example: "+1234567890"
payloadobjectread-only

Lead custom variables. This object can contain any key, but the values have to be of type string, number, boolean, or null. We do NOT allow objects or arrays as values.

status_summary_subseqobjectread-only

Subsequence status summary of the lead

last_step_fromstringread-only

Source of the last step

Example: "campaign"
last_step_idstring(uuid)read-only

ID of the last step

Example: "01959272-5d2b-7a87-a5d7-19a341212045"
last_step_timestamp_executedstring(date-time)read-only

Timestamp when the last step was executed

Example: "2025-03-14T02:18:43.371Z"
email_opened_stepnumberread-only

Last email step opened by the lead

Example: 1
email_opened_variantnumberread-only

Last step variant opened by the lead

Example: 1
email_replied_stepnumberread-only

Last email step the lead has replied to

Example: 1
email_replied_variantnumberread-only

Last step variant the lead has replied to

Example: 1
email_clicked_stepnumberread-only

Last email step the lead has clicked

Example: 1
email_clicked_variantnumberread-only

Last step variant the lead has clicked

Example: 1
lt_interest_statusnumber

Lead interest status. It can be either a static value (check below), or a custom status interest value

Enum ValueDescription
0

Out of Office

1

Interested

2

Meeting Booked

3

Meeting Completed

4

Closed

-1

Not Interested

-2

Wrong Person

-3

Lost

Example: 1
subsequence_idstringread-only

ID of the subsequence

Example: "01959272-5d2b-7a87-a5d7-19a4a1eedf0d"
verification_statusnumberread-only

Verification status of the lead

Enum ValueDescription
1

Verified

11

Pending

12

Pending Verification Job

-1

Invalid

-2

Risky

-3

Catch All

-4

Job Change

Example: 1
pl_value_leadstring

Potential value of the lead

Example: "High"
timestamp_added_subsequencestring(date-time)read-only

Timestamp when the lead was added to the subsequence

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_contactstring(date-time)read-only

Timestamp of the last contact with the lead

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_openstring(date-time)read-only

Timestamp of the last email open

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_replystring(date-time)read-only

Timestamp of the last email reply

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_interest_changestring(date-time)read-only

Timestamp of the last interest status change

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_clickstring(date-time)read-only

Timestamp of the last email click

Example: "2025-03-14T02:18:43.371Z"
enrichment_statusnumberread-only

Enrichment status of the lead

Enum ValueDescription
1

Enriched

11

Pending

-1

Enrichment data not available

-2

Error

Example: 1
list_idstring(uuid)

List ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-19a53f860c5e"
last_contacted_fromstringread-only

Source of the last contact

Example: "email"
uploaded_by_userstring(uuid)read-only

ID of the user who uploaded the lead

Example: "01959272-5d2b-7a87-a5d7-19a694ff3588"
upload_methodstringread-only

Method used to upload the lead

Enum ValueDescription
manual

Manual

api

API

website-visitor

Website Visitor

Example: "manual"
assigned_tostring(uuid)

ID of the user assigned to the lead

Example: "01959272-5d2b-7a87-a5d7-19a7ec8d1ed6"
is_website_visitorbooleanread-only

Indicates if the lead is a website visitor

Example: true
timestamp_last_touchstring(date-time)read-only

Timestamp of the last touch with the lead

Example: "2025-03-14T02:18:43.371Z"
esp_codenumberread-only

ESP code associated with the lead

Enum ValueDescription
0

In Queue

1

Google

2

Microsoft

3

Zoho

9

Yahoo

10

Yandex

12

Web.de

13

Libero.it

999

Other

1000

Not Found

Example: 1
Response
application/json
{
  "id": "01959272-5d2b-7a87-a5d7-199e472e6366",
  "timestamp_created": "2025-03-14T02:18:43.371Z",
  "timestamp_updated": "2025-03-14T02:18:43.371Z",
  "organization": "01959272-5d2b-7a87-a5d7-199f18e7bfc7",
  "campaign": "01959272-5d2b-7a87-a5d7-19a0c5e1fc64",
  "status": 1,
  "email": "example@example.com",
  "personalization": "Hello, how are you?",
  "website": "https://example.com",
  "last_name": "Doe",
  "first_name": "John",
  "company_name": "Example Inc.",
  "phone": "+1234567890",
  "email_open_count": 0,
  "email_reply_count": 0,
  "email_click_count": 0,
  "company_domain": "example.com",
  "status_summary": {
    "from": "campaign",
    "stepID": "01959272-5d2b-7a87-a5d7-19a16e3e6e6d",
    "timestamp_executed": "2025-03-14T02:18:43.371Z"
  },
  "payload": {
    "firstName": "John",
    "lastName": "Doe",
    "companyName": "Acme Corp",
    "website": "https://example.com",
    "phone": "+1234567890",
    "personalization": "Hi {{first_name}}, I noticed you work at {{company_name}}...",
    "property1": null,
    "property2": null
  },
  "status_summary_subseq": {
    "from": "campaign",
    "stepID": "01959272-5d2b-7a87-a5d7-19a2b3a9c292",
    "timestampExecuted": "2025-03-14T02:18:43.371Z"
  },
  "last_step_from": "campaign",
  "last_step_id": "01959272-5d2b-7a87-a5d7-19a341212045",
  "last_step_timestamp_executed": "2025-03-14T02:18:43.371Z",
  "email_opened_step": 1,
  "email_opened_variant": 1,
  "email_replied_step": 1,
  "email_replied_variant": 1,
  "email_clicked_step": 1,
  "email_clicked_variant": 1,
  "lt_interest_status": 1,
  "subsequence_id": "01959272-5d2b-7a87-a5d7-19a4a1eedf0d",
  "verification_status": 1,
  "pl_value_lead": "High",
  "timestamp_added_subsequence": "2025-03-14T02:18:43.371Z",
  "timestamp_last_contact": "2025-03-14T02:18:43.371Z",
  "timestamp_last_open": "2025-03-14T02:18:43.371Z",
  "timestamp_last_reply": "2025-03-14T02:18:43.371Z",
  "timestamp_last_interest_change": "2025-03-14T02:18:43.371Z",
  "timestamp_last_click": "2025-03-14T02:18:43.371Z",
  "enrichment_status": 1,
  "list_id": "01959272-5d2b-7a87-a5d7-19a53f860c5e",
  "last_contacted_from": "email",
  "uploaded_by_user": "01959272-5d2b-7a87-a5d7-19a694ff3588",
  "upload_method": "manual",
  "assigned_to": "01959272-5d2b-7a87-a5d7-19a7ec8d1ed6",
  "is_website_visitor": true,
  "timestamp_last_touch": "2025-03-14T02:18:43.371Z",
  "esp_code": 1
}

Update the interest status of a lead

Request

Update the interest status of a lead

Bodyapplication/jsonrequired
lead_emailstringrequired
Example: "test@test.com"
interest_valuenumberrequired
Example: 1
campaign_idstring
Example: "01959272-6e9a-71e3-b009-85aafe5b016b"
ai_interest_valuenumber
Example: 1
disable_auto_interestboolean
Example: true
list_idstring
Example: "01959272-6e9a-71e3-b009-85abf13cafe4"
curl -i -X POST \
  https://api.instantly.ai/api/v2/leads/update-interest-status \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "lead_email": "test@test.com",
    "interest_value": 1
  }'

Responses

Default Response

Bodyapplication/json
messagestring
Example: "Lead interest status update background job submitted"
Response
application/json
{
  "message": "Lead interest status update background job submitted"
}

Remove a lead from a subsequence

Request

Remove a lead from a subsequence

Requires one of the following scopes: leads:update, leads:all, all:update, all:all

Bodyapplication/jsonrequired
idstring(uuid)required
Example: "01959272-6e9a-71e3-b009-85ac16b2be7f"
curl -i -X POST \
  https://api.instantly.ai/api/v2/leads/subsequence/remove \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "01959272-6e9a-71e3-b009-85ac16b2be7f"
  }'

Responses

The requested Lead

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the lead

Example: "01959272-5d2b-7a87-a5d7-199e472e6366"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the lead was created

Example: "2025-03-14T02:18:43.371Z"
timestamp_updatedstring(date-time)read-onlyrequired

Timestamp when the lead was last updated

Example: "2025-03-14T02:18:43.371Z"
organizationstring(uuid)read-onlyrequired

Organization ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-199f18e7bfc7"
statusnumberread-onlyrequired

Status of the lead

Enum ValueDescription
1

Active

2

Paused

3

Completed

-1

Bounced

-2

Unsubscribed

-3

Skipped

Example: 1
email_open_countnumberread-onlyrequired

Number of times the email was opened

Example: 0
email_reply_countnumberread-onlyrequired

Number of times the email was replied to

Example: 0
email_click_countnumberread-onlyrequired

Number of times the email was clicked

Example: 0
company_domainstringread-onlyrequired

Company domain of the lead

Example: "example.com"
status_summaryobjectread-onlyrequired

Status summary of the lead

status_summary.​fromstring
Example: "campaign"
status_summary.​stepIDstring
Example: "01959272-5d2b-7a87-a5d7-19a16e3e6e6d"
status_summary.​timestamp_executedstring(date-time)
Example: "2025-03-14T02:18:43.371Z"
campaignstring(uuid)

Campaign ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-19a0c5e1fc64"
emailstring

Email address of the lead

Example: "example@example.com"
personalizationstring

Personalization of the lead

Example: "Hello, how are you?"
websitestring

Website of the lead

Example: "https://example.com"
last_namestring

Last name of the lead

Example: "Doe"
first_namestring

First name of the lead

Example: "John"
company_namestring

Company name of the lead

Example: "Example Inc."
phonestring

Phone number of the lead

Example: "+1234567890"
payloadobjectread-only

Lead custom variables. This object can contain any key, but the values have to be of type string, number, boolean, or null. We do NOT allow objects or arrays as values.

status_summary_subseqobjectread-only

Subsequence status summary of the lead

last_step_fromstringread-only

Source of the last step

Example: "campaign"
last_step_idstring(uuid)read-only

ID of the last step

Example: "01959272-5d2b-7a87-a5d7-19a341212045"
last_step_timestamp_executedstring(date-time)read-only

Timestamp when the last step was executed

Example: "2025-03-14T02:18:43.371Z"
email_opened_stepnumberread-only

Last email step opened by the lead

Example: 1
email_opened_variantnumberread-only

Last step variant opened by the lead

Example: 1
email_replied_stepnumberread-only

Last email step the lead has replied to

Example: 1
email_replied_variantnumberread-only

Last step variant the lead has replied to

Example: 1
email_clicked_stepnumberread-only

Last email step the lead has clicked

Example: 1
email_clicked_variantnumberread-only

Last step variant the lead has clicked

Example: 1
lt_interest_statusnumber

Lead interest status. It can be either a static value (check below), or a custom status interest value

Enum ValueDescription
0

Out of Office

1

Interested

2

Meeting Booked

3

Meeting Completed

4

Closed

-1

Not Interested

-2

Wrong Person

-3

Lost

Example: 1
subsequence_idstringread-only

ID of the subsequence

Example: "01959272-5d2b-7a87-a5d7-19a4a1eedf0d"
verification_statusnumberread-only

Verification status of the lead

Enum ValueDescription
1

Verified

11

Pending

12

Pending Verification Job

-1

Invalid

-2

Risky

-3

Catch All

-4

Job Change

Example: 1
pl_value_leadstring

Potential value of the lead

Example: "High"
timestamp_added_subsequencestring(date-time)read-only

Timestamp when the lead was added to the subsequence

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_contactstring(date-time)read-only

Timestamp of the last contact with the lead

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_openstring(date-time)read-only

Timestamp of the last email open

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_replystring(date-time)read-only

Timestamp of the last email reply

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_interest_changestring(date-time)read-only

Timestamp of the last interest status change

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_clickstring(date-time)read-only

Timestamp of the last email click

Example: "2025-03-14T02:18:43.371Z"
enrichment_statusnumberread-only

Enrichment status of the lead

Enum ValueDescription
1

Enriched

11

Pending

-1

Enrichment data not available

-2

Error

Example: 1
list_idstring(uuid)

List ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-19a53f860c5e"
last_contacted_fromstringread-only

Source of the last contact

Example: "email"
uploaded_by_userstring(uuid)read-only

ID of the user who uploaded the lead

Example: "01959272-5d2b-7a87-a5d7-19a694ff3588"
upload_methodstringread-only

Method used to upload the lead

Enum ValueDescription
manual

Manual

api

API

website-visitor

Website Visitor

Example: "manual"
assigned_tostring(uuid)

ID of the user assigned to the lead

Example: "01959272-5d2b-7a87-a5d7-19a7ec8d1ed6"
is_website_visitorbooleanread-only

Indicates if the lead is a website visitor

Example: true
timestamp_last_touchstring(date-time)read-only

Timestamp of the last touch with the lead

Example: "2025-03-14T02:18:43.371Z"
esp_codenumberread-only

ESP code associated with the lead

Enum ValueDescription
0

In Queue

1

Google

2

Microsoft

3

Zoho

9

Yahoo

10

Yandex

12

Web.de

13

Libero.it

999

Other

1000

Not Found

Example: 1
Response
application/json
{
  "id": "01959272-5d2b-7a87-a5d7-199e472e6366",
  "timestamp_created": "2025-03-14T02:18:43.371Z",
  "timestamp_updated": "2025-03-14T02:18:43.371Z",
  "organization": "01959272-5d2b-7a87-a5d7-199f18e7bfc7",
  "campaign": "01959272-5d2b-7a87-a5d7-19a0c5e1fc64",
  "status": 1,
  "email": "example@example.com",
  "personalization": "Hello, how are you?",
  "website": "https://example.com",
  "last_name": "Doe",
  "first_name": "John",
  "company_name": "Example Inc.",
  "phone": "+1234567890",
  "email_open_count": 0,
  "email_reply_count": 0,
  "email_click_count": 0,
  "company_domain": "example.com",
  "status_summary": {
    "from": "campaign",
    "stepID": "01959272-5d2b-7a87-a5d7-19a16e3e6e6d",
    "timestamp_executed": "2025-03-14T02:18:43.371Z"
  },
  "payload": {
    "firstName": "John",
    "lastName": "Doe",
    "companyName": "Acme Corp",
    "website": "https://example.com",
    "phone": "+1234567890",
    "personalization": "Hi {{first_name}}, I noticed you work at {{company_name}}...",
    "property1": null,
    "property2": null
  },
  "status_summary_subseq": {
    "from": "campaign",
    "stepID": "01959272-5d2b-7a87-a5d7-19a2b3a9c292",
    "timestampExecuted": "2025-03-14T02:18:43.371Z"
  },
  "last_step_from": "campaign",
  "last_step_id": "01959272-5d2b-7a87-a5d7-19a341212045",
  "last_step_timestamp_executed": "2025-03-14T02:18:43.371Z",
  "email_opened_step": 1,
  "email_opened_variant": 1,
  "email_replied_step": 1,
  "email_replied_variant": 1,
  "email_clicked_step": 1,
  "email_clicked_variant": 1,
  "lt_interest_status": 1,
  "subsequence_id": "01959272-5d2b-7a87-a5d7-19a4a1eedf0d",
  "verification_status": 1,
  "pl_value_lead": "High",
  "timestamp_added_subsequence": "2025-03-14T02:18:43.371Z",
  "timestamp_last_contact": "2025-03-14T02:18:43.371Z",
  "timestamp_last_open": "2025-03-14T02:18:43.371Z",
  "timestamp_last_reply": "2025-03-14T02:18:43.371Z",
  "timestamp_last_interest_change": "2025-03-14T02:18:43.371Z",
  "timestamp_last_click": "2025-03-14T02:18:43.371Z",
  "enrichment_status": 1,
  "list_id": "01959272-5d2b-7a87-a5d7-19a53f860c5e",
  "last_contacted_from": "email",
  "uploaded_by_user": "01959272-5d2b-7a87-a5d7-19a694ff3588",
  "upload_method": "manual",
  "assigned_to": "01959272-5d2b-7a87-a5d7-19a7ec8d1ed6",
  "is_website_visitor": true,
  "timestamp_last_touch": "2025-03-14T02:18:43.371Z",
  "esp_code": 1
}

Bulk assign leads to organization users

Request

Bulk assign leads to organization users

Bodyapplication/jsonrequired
organization_user_idsArray of strings(uuid)non-emptyrequired
searchstring
Example: "test"
filterstring
Example: "test"
campaignstring(uuid)
Example: "01959272-6e9b-74d5-8bc0-b159152593b8"
list_idstring(uuid)
Example: "01959272-6e9b-74d5-8bc0-b15af4c1bd2e"
in_campaignboolean
Example: true
in_listboolean
Example: true
smart_view_idstring(uuid)
Example: "01959272-6e9b-74d5-8bc0-b15b73a9dd1e"
idsArray of strings(uuid)
Example: ["01959272-6e9b-74d5-8bc0-b15c164ad413"]
limitinteger>= 0
Example: 10
queriesArray of objects
curl -i -X POST \
  https://api.instantly.ai/api/v2/leads/bulk-assign \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "organization_user_ids": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ]
  }'

Responses

Default Response

Bodyapplication/json
statusstring
Example: "accepted"
messagestring
Example: "Your request will be processed in a background job"
Response
application/json
{
  "status": "accepted",
  "message": "Your request will be processed in a background job"
}

Move leads to a campaign or list

Request

Move leads to a different campaign or list. This endpoint will return a background job that will process the move. The job will be processed in the background and the leads will be moved to the destination campaign or list. You can use the /background-jobs/:id endpoint to check the job status.

Requires one of the following scopes: leads:update, leads:all, all:update, all:all

Bodyapplication/json
searchstring

A search string to search the leads against - can be First Name, Last Name, or Email

Example: "John Doe"
filterstring

Filter criteria for leads. For custom lead labels, use the interest_status field.

Enum ValueDescription
FILTER_VAL_CONTACTED

Filter for contacted leads

FILTER_VAL_NOT_CONTACTED

Filter for not contacted leads

FILTER_VAL_COMPLETED

Filter for completed leads

FILTER_VAL_UNSUBSCRIBED

Filter for unsubscribed leads

FILTER_VAL_ACTIVE

Filter for active leads

FILTER_LEAD_INTERESTED

Filter for interested leads

FILTER_LEAD_NOT_INTERESTED

Filter for not interested leads

FILTER_LEAD_MEETING_BOOKED

Filter for leads with meeting booked

FILTER_LEAD_MEETING_COMPLETED

Filter for leads with meeting completed

FILTER_LEAD_CLOSED

Filter for closed leads

Example: "FILTER_VAL_CONTACTED"
campaignstring(uuid)

Campaign ID to filter leads

Example: "01959272-6b00-7524-b40c-0cc8d9a36467"
list_idstring(uuid)

List ID to filter leads

Example: "01959272-6b00-7524-b40c-0cc986e87ac6"
in_campaignboolean

Whether the lead is in a campaign

Example: true
in_listboolean

Whether the lead is in a list

Example: true
idsArray of strings(uuid)

Array of lead IDs to include

queriesArray of objects
Example: [{"actionType":"email-open","values":{"occurrence-days":1}}]
excluded_idsArray of strings(uuid)

Array of lead IDs to exclude

contactsArray of strings(email)

Array of emails the leads needs to have

to_campaign_idstring(uuid)
Example: "01959272-6e9b-74d5-8bc0-b15d348f0961"
to_list_idstring(uuid)
Example: "01959272-6e9b-74d5-8bc0-b15e79ee38c8"
check_duplicates_in_campaignsboolean
Example: true
skip_leads_in_verificationboolean
Example: true
limitnumber
Example: 10
assigned_tostring(uuid)
Example: "01959272-6e9b-74d5-8bc0-b15f7d0137a3"
esp_codenumber
Enum ValueDescription
0

In Queue

1

Google

2

Microsoft

3

Zoho

9

Yahoo

10

Yandex

12

Webde

13

Liberoit

999

Other

1000

Not Found

Example: 1
curl -i -X POST \
  https://api.instantly.ai/api/v2/leads/move \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

The requested Background Job

Bodyapplication/json
idstringread-onlyrequired

Unique identifier for the background job

Example: "675266e304a8e55b17f0228b"
workspace_idstring(uuid)read-onlyrequired

Workspace ID

Example: "01959272-5de9-7930-9984-b0fbfdaa187e"
typestringrequired

Type of background job

Enum ValueDescription
move-leads

Move Leads

import-leads

Import Leads

Example: "move-leads"
progressnumber[ 0 .. 100 ]required

Progress of the job as a percentage (from 0 to 100)

Example: 0
statusstringrequired

Job status

Enum ValueDescription
pending

The background job is waiting in the queue to be processed

in-progress

The background job is being processed

success

The background job has been successfully processed

failed

The background job has failed

Example: "pending"
created_atstringrequired

Timestamp when the job was created

Example: "2025-03-14T02:18:43.561Z"
updated_atstringrequired

Timestamp when the job was last updated

Example: "2025-03-14T02:18:43.561Z"
user_idstring(uuid)read-only

The id of the user that triggered the action that created the job

Example: "01959272-5de9-7930-9984-b0fc322edb8b"
entity_idstring(uuid)

The id of the entity that the job is related to

Example: "01959272-5de9-7930-9984-b0fd195c81a5"
entity_typestring

Type of entity

Enum ValueDescription
list

The entity is a lead list

campaign

The entity is a campaign

Example: "list"
dataobject

Data about the job, used to store any additional information we need to process the job

Response
application/json
{
  "id": "675266e304a8e55b17f0228b",
  "workspace_id": "01959272-5de9-7930-9984-b0fbfdaa187e",
  "user_id": "01959272-5de9-7930-9984-b0fc322edb8b",
  "type": "move-leads",
  "entity_id": "01959272-5de9-7930-9984-b0fd195c81a5",
  "entity_type": "list",
  "data": {},
  "progress": 0,
  "status": "pending",
  "created_at": "2025-03-14T02:18:43.561Z",
  "updated_at": "2025-03-14T02:18:43.561Z"
}

Move a lead to a subsequence

Request

Move a lead to a subsequence

Requires one of the following scopes: leads:update, leads:all, all:update, all:all

Bodyapplication/jsonrequired
idstring(uuid)required
Example: "01959272-6e9c-72e0-a2c9-9185109bd4a2"
subsequence_idstring(uuid)required
Example: "01959272-6e9c-72e0-a2c9-91842402236e"
curl -i -X POST \
  https://api.instantly.ai/api/v2/leads/subsequence/move \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "subsequence_id": "01959272-6e9c-72e0-a2c9-91842402236e",
    "id": "01959272-6e9c-72e0-a2c9-9185109bd4a2"
  }'

Responses

The requested Lead

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the lead

Example: "01959272-5d2b-7a87-a5d7-199e472e6366"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the lead was created

Example: "2025-03-14T02:18:43.371Z"
timestamp_updatedstring(date-time)read-onlyrequired

Timestamp when the lead was last updated

Example: "2025-03-14T02:18:43.371Z"
organizationstring(uuid)read-onlyrequired

Organization ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-199f18e7bfc7"
statusnumberread-onlyrequired

Status of the lead

Enum ValueDescription
1

Active

2

Paused

3

Completed

-1

Bounced

-2

Unsubscribed

-3

Skipped

Example: 1
email_open_countnumberread-onlyrequired

Number of times the email was opened

Example: 0
email_reply_countnumberread-onlyrequired

Number of times the email was replied to

Example: 0
email_click_countnumberread-onlyrequired

Number of times the email was clicked

Example: 0
company_domainstringread-onlyrequired

Company domain of the lead

Example: "example.com"
status_summaryobjectread-onlyrequired

Status summary of the lead

status_summary.​fromstring
Example: "campaign"
status_summary.​stepIDstring
Example: "01959272-5d2b-7a87-a5d7-19a16e3e6e6d"
status_summary.​timestamp_executedstring(date-time)
Example: "2025-03-14T02:18:43.371Z"
campaignstring(uuid)

Campaign ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-19a0c5e1fc64"
emailstring

Email address of the lead

Example: "example@example.com"
personalizationstring

Personalization of the lead

Example: "Hello, how are you?"
websitestring

Website of the lead

Example: "https://example.com"
last_namestring

Last name of the lead

Example: "Doe"
first_namestring

First name of the lead

Example: "John"
company_namestring

Company name of the lead

Example: "Example Inc."
phonestring

Phone number of the lead

Example: "+1234567890"
payloadobjectread-only

Lead custom variables. This object can contain any key, but the values have to be of type string, number, boolean, or null. We do NOT allow objects or arrays as values.

status_summary_subseqobjectread-only

Subsequence status summary of the lead

last_step_fromstringread-only

Source of the last step

Example: "campaign"
last_step_idstring(uuid)read-only

ID of the last step

Example: "01959272-5d2b-7a87-a5d7-19a341212045"
last_step_timestamp_executedstring(date-time)read-only

Timestamp when the last step was executed

Example: "2025-03-14T02:18:43.371Z"
email_opened_stepnumberread-only

Last email step opened by the lead

Example: 1
email_opened_variantnumberread-only

Last step variant opened by the lead

Example: 1
email_replied_stepnumberread-only

Last email step the lead has replied to

Example: 1
email_replied_variantnumberread-only

Last step variant the lead has replied to

Example: 1
email_clicked_stepnumberread-only

Last email step the lead has clicked

Example: 1
email_clicked_variantnumberread-only

Last step variant the lead has clicked

Example: 1
lt_interest_statusnumber

Lead interest status. It can be either a static value (check below), or a custom status interest value

Enum ValueDescription
0

Out of Office

1

Interested

2

Meeting Booked

3

Meeting Completed

4

Closed

-1

Not Interested

-2

Wrong Person

-3

Lost

Example: 1
subsequence_idstringread-only

ID of the subsequence

Example: "01959272-5d2b-7a87-a5d7-19a4a1eedf0d"
verification_statusnumberread-only

Verification status of the lead

Enum ValueDescription
1

Verified

11

Pending

12

Pending Verification Job

-1

Invalid

-2

Risky

-3

Catch All

-4

Job Change

Example: 1
pl_value_leadstring

Potential value of the lead

Example: "High"
timestamp_added_subsequencestring(date-time)read-only

Timestamp when the lead was added to the subsequence

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_contactstring(date-time)read-only

Timestamp of the last contact with the lead

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_openstring(date-time)read-only

Timestamp of the last email open

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_replystring(date-time)read-only

Timestamp of the last email reply

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_interest_changestring(date-time)read-only

Timestamp of the last interest status change

Example: "2025-03-14T02:18:43.371Z"
timestamp_last_clickstring(date-time)read-only

Timestamp of the last email click

Example: "2025-03-14T02:18:43.371Z"
enrichment_statusnumberread-only

Enrichment status of the lead

Enum ValueDescription
1

Enriched

11

Pending

-1

Enrichment data not available

-2

Error

Example: 1
list_idstring(uuid)

List ID associated with the lead

Example: "01959272-5d2b-7a87-a5d7-19a53f860c5e"
last_contacted_fromstringread-only

Source of the last contact

Example: "email"
uploaded_by_userstring(uuid)read-only

ID of the user who uploaded the lead

Example: "01959272-5d2b-7a87-a5d7-19a694ff3588"
upload_methodstringread-only

Method used to upload the lead

Enum ValueDescription
manual

Manual

api

API

website-visitor

Website Visitor

Example: "manual"
assigned_tostring(uuid)

ID of the user assigned to the lead

Example: "01959272-5d2b-7a87-a5d7-19a7ec8d1ed6"
is_website_visitorbooleanread-only

Indicates if the lead is a website visitor

Example: true
timestamp_last_touchstring(date-time)read-only

Timestamp of the last touch with the lead

Example: "2025-03-14T02:18:43.371Z"
esp_codenumberread-only

ESP code associated with the lead

Enum ValueDescription
0

In Queue

1

Google

2

Microsoft

3

Zoho

9

Yahoo

10

Yandex

12

Web.de

13

Libero.it

999

Other

1000

Not Found

Example: 1
Response
application/json
{
  "id": "01959272-5d2b-7a87-a5d7-199e472e6366",
  "timestamp_created": "2025-03-14T02:18:43.371Z",
  "timestamp_updated": "2025-03-14T02:18:43.371Z",
  "organization": "01959272-5d2b-7a87-a5d7-199f18e7bfc7",
  "campaign": "01959272-5d2b-7a87-a5d7-19a0c5e1fc64",
  "status": 1,
  "email": "example@example.com",
  "personalization": "Hello, how are you?",
  "website": "https://example.com",
  "last_name": "Doe",
  "first_name": "John",
  "company_name": "Example Inc.",
  "phone": "+1234567890",
  "email_open_count": 0,
  "email_reply_count": 0,
  "email_click_count": 0,
  "company_domain": "example.com",
  "status_summary": {
    "from": "campaign",
    "stepID": "01959272-5d2b-7a87-a5d7-19a16e3e6e6d",
    "timestamp_executed": "2025-03-14T02:18:43.371Z"
  },
  "payload": {
    "firstName": "John",
    "lastName": "Doe",
    "companyName": "Acme Corp",
    "website": "https://example.com",
    "phone": "+1234567890",
    "personalization": "Hi {{first_name}}, I noticed you work at {{company_name}}...",
    "property1": null,
    "property2": null
  },
  "status_summary_subseq": {
    "from": "campaign",
    "stepID": "01959272-5d2b-7a87-a5d7-19a2b3a9c292",
    "timestampExecuted": "2025-03-14T02:18:43.371Z"
  },
  "last_step_from": "campaign",
  "last_step_id": "01959272-5d2b-7a87-a5d7-19a341212045",
  "last_step_timestamp_executed": "2025-03-14T02:18:43.371Z",
  "email_opened_step": 1,
  "email_opened_variant": 1,
  "email_replied_step": 1,
  "email_replied_variant": 1,
  "email_clicked_step": 1,
  "email_clicked_variant": 1,
  "lt_interest_status": 1,
  "subsequence_id": "01959272-5d2b-7a87-a5d7-19a4a1eedf0d",
  "verification_status": 1,
  "pl_value_lead": "High",
  "timestamp_added_subsequence": "2025-03-14T02:18:43.371Z",
  "timestamp_last_contact": "2025-03-14T02:18:43.371Z",
  "timestamp_last_open": "2025-03-14T02:18:43.371Z",
  "timestamp_last_reply": "2025-03-14T02:18:43.371Z",
  "timestamp_last_interest_change": "2025-03-14T02:18:43.371Z",
  "timestamp_last_click": "2025-03-14T02:18:43.371Z",
  "enrichment_status": 1,
  "list_id": "01959272-5d2b-7a87-a5d7-19a53f860c5e",
  "last_contacted_from": "email",
  "uploaded_by_user": "01959272-5d2b-7a87-a5d7-19a694ff3588",
  "upload_method": "manual",
  "assigned_to": "01959272-5d2b-7a87-a5d7-19a7ec8d1ed6",
  "is_website_visitor": true,
  "timestamp_last_touch": "2025-03-14T02:18:43.371Z",
  "esp_code": 1
}

Background Job

A background job that can be used to perform long-running tasks

Operations

Custom Tag

A custom tag for organizing and categorizing items

Operations

Block List Entry

A blocked email or domain

Operations

Lead Label

A custom label for categorizing and managing leads

Operations

Workspace

A workspace entity representing a workspace

Operations

Workspace Group Member

A member of a workspace group. You can use the endpoints within this entity to manage the members of a workspace group.

Operations

Workspace Member

A member of a workspace with associated user details

Operations

Campaign Subsequence

A subsequence entity representing a follow-up sequence

Operations

Schemas