Schemas
/
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

Background Job

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

Operations

Custom Tag

A custom tag for organizing and categorizing accounts and campaigns. You can use them as filters in apis that list accounts and campaigns.

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

Audit Log

Audit log records for tracking system activities

Operations

Schemas

Account Campaign Mapping

Account Campaign Mapping

campaign_idstring(uuid)required
Example: "019769d6-c114-74c3-8add-d1f21b269fda"
campaign_namestringrequired
Example: "Campaign Name"
timestamp_createdstringread-onlyrequired

Timestamp when the campaign was created

Example: "2025-06-13T15:09:31.284Z"
statusnumber

Campaign Status

Enum ValueDescription
0

Draft

1

Active

2

Paused

3

Completed

4

Running Subsequences

-99

Account Suspended

-1

Accounts Unhealthy

-2

Bounce Protect

Example: 1
{
  "campaign_id": "019769d6-c114-74c3-8add-d1f21b269fda",
  "campaign_name": "Campaign Name",
  "timestamp_created": "2025-06-13T15:09:31.284Z",
  "status": 1
}

Lead

A lead entity representing an individual lead

idstring(uuid)read-onlyrequired

Unique identifier for the lead

Example: "019769d6-beb2-7631-9d96-caa0c5583bb2"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the lead was created

Example: "2025-06-13T15:09:30.676Z"
timestamp_updatedstring(date-time)read-onlyrequired

Timestamp when the lead was last updated

Example: "2025-06-13T15:09:30.677Z"
organizationstring(uuid)read-onlyrequired

Organization ID associated with the lead

Example: "019769d6-beb5-7016-87a3-eb22de6a66cd"
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: "019769d6-beb5-7016-87a3-eb2492f5a745"
status_summary.​timestamp_executedstring(date-time)
Example: "2025-06-13T15:09:30.677Z"
campaignnull or string(uuid)

Campaign ID associated with the lead

Example: "019769d6-beb5-7016-87a3-eb2374ec279a"
emailnull or string

Email address of the lead

Example: "example@example.com"
personalizationnull or string

Personalization of the lead

Example: "Hello, how are you?"
websitenull or string

Website of the lead

Example: "https://example.com"
last_namenull or string

Last name of the lead

Example: "Doe"
first_namenull or string

First name of the lead

Example: "John"
company_namenull or string

Company name of the lead

Example: "Example Inc."
phonenull or string

Phone number of the lead

Example: "+1234567890"
payloadnull or objectread-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_fromnull or stringread-only

Source of the last step

Example: "campaign"
last_step_idnull or string(uuid)read-only

ID of the last step

Example: "019769d6-beb5-7016-87a3-eb268143b9cb"
last_step_timestamp_executednull or string(date-time)read-only

Timestamp when the last step was executed

Example: "2025-06-13T15:09:30.677Z"
email_opened_stepnull or numberread-only

Last email step opened by the lead

Example: 1
email_opened_variantnull or numberread-only

Last step variant opened by the lead

Example: 1
email_replied_stepnull or numberread-only

Last email step the lead has replied to

Example: 1
email_replied_variantnull or numberread-only

Last step variant the lead has replied to

Example: 1
email_clicked_stepnull or numberread-only

Last email step the lead has clicked

Example: 1
email_clicked_variantnull or numberread-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_idnull or stringread-only

ID of the subsequence

Example: "019769d6-beb5-7016-87a3-eb27c3017fb7"
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_leadnull or string

Potential value of the lead

Example: "High"
timestamp_added_subsequencenull or string(date-time)read-only

Timestamp when the lead was added to the subsequence

Example: "2025-06-13T15:09:30.677Z"
timestamp_last_contactnull or string(date-time)read-only

Timestamp of the last contact with the lead

Example: "2025-06-13T15:09:30.677Z"
timestamp_last_opennull or string(date-time)read-only

Timestamp of the last email open

Example: "2025-06-13T15:09:30.677Z"
timestamp_last_replynull or string(date-time)read-only

Timestamp of the last email reply

Example: "2025-06-13T15:09:30.677Z"
timestamp_last_interest_changenull or string(date-time)read-only

Timestamp of the last interest status change

Example: "2025-06-13T15:09:30.677Z"
timestamp_last_clicknull or string(date-time)read-only

Timestamp of the last email click

Example: "2025-06-13T15:09:30.677Z"
enrichment_statusnumberread-only

Enrichment status of the lead

Enum ValueDescription
1

Enriched

11

Pending

-1

Enrichment data not available

-2

Error

Example: 1
list_idnull or string(uuid)

List ID associated with the lead

Example: "019769d6-beb5-7016-87a3-eb28acb6e0e9"
last_contacted_fromnull or stringread-only

Source of the last contact

Example: "email"
uploaded_by_usernull or string(uuid)read-only

ID of the user who uploaded the lead

Example: "019769d6-beb5-7016-87a3-eb296541167a"
upload_methodstringread-only

Method used to upload the lead

Enum ValueDescription
manual

Manual

api

API

website-visitor

Website Visitor

Example: "manual"
assigned_tonull or string(uuid)

ID of the user assigned to the lead

Example: "019769d6-beb5-7016-87a3-eb2a994200af"
is_website_visitornull or booleanread-only

Indicates if the lead is a website visitor

Example: true
timestamp_last_touchnull or string(date-time)read-only

Timestamp of the last touch with the lead

Example: "2025-06-13T15:09:30.678Z"
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": "019769d6-beb2-7631-9d96-caa0c5583bb2",
  "timestamp_created": "2025-06-13T15:09:30.676Z",
  "timestamp_updated": "2025-06-13T15:09:30.677Z",
  "organization": "019769d6-beb5-7016-87a3-eb22de6a66cd",
  "campaign": "019769d6-beb5-7016-87a3-eb2374ec279a",
  "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": "019769d6-beb5-7016-87a3-eb2492f5a745",
    "timestamp_executed": "2025-06-13T15:09:30.677Z"
  },
  "payload": null,
  "status_summary_subseq": {
    "from": "campaign",
    "stepID": "019769d6-beb5-7016-87a3-eb25c01e8f26",
    "timestampExecuted": "2025-06-13T15:09:30.677Z"
  },
  "last_step_from": "campaign",
  "last_step_id": "019769d6-beb5-7016-87a3-eb268143b9cb",
  "last_step_timestamp_executed": "2025-06-13T15:09:30.677Z",
  "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": "019769d6-beb5-7016-87a3-eb27c3017fb7",
  "verification_status": 1,
  "pl_value_lead": "High",
  "timestamp_added_subsequence": "2025-06-13T15:09:30.677Z",
  "timestamp_last_contact": "2025-06-13T15:09:30.677Z",
  "timestamp_last_open": "2025-06-13T15:09:30.677Z",
  "timestamp_last_reply": "2025-06-13T15:09:30.677Z",
  "timestamp_last_interest_change": "2025-06-13T15:09:30.677Z",
  "timestamp_last_click": "2025-06-13T15:09:30.677Z",
  "enrichment_status": 1,
  "list_id": "019769d6-beb5-7016-87a3-eb28acb6e0e9",
  "last_contacted_from": "email",
  "uploaded_by_user": "019769d6-beb5-7016-87a3-eb296541167a",
  "upload_method": "manual",
  "assigned_to": "019769d6-beb5-7016-87a3-eb2a994200af",
  "is_website_visitor": true,
  "timestamp_last_touch": "2025-06-13T15:09:30.678Z",
  "esp_code": 1
}

Background Job

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

idstringread-onlyrequired

Unique identifier for the background job

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

Workspace ID

Example: "019769d6-c12f-7564-8f02-95c86f110e4f"
typestringrequired

Type of background job

Enum ValueDescription
move-leads

Move Leads

import-leads

Import Leads

export-leads

Export 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-06-13T15:09:31.311Z"
updated_atstringrequired

Timestamp when the job was last updated

Example: "2025-06-13T15:09:31.311Z"
user_idnull or string(uuid)read-only

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

Example: "019769d6-c12f-7564-8f02-95c937780ee4"
entity_idnull or string(uuid)

The id of the entity that the job is related to

Example: "019769d6-c12f-7564-8f02-95ca1a1310a8"
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

{
  "id": "675266e304a8e55b17f0228b",
  "workspace_id": "019769d6-c12f-7564-8f02-95c86f110e4f",
  "user_id": "019769d6-c12f-7564-8f02-95c937780ee4",
  "type": "move-leads",
  "entity_id": "019769d6-c12f-7564-8f02-95ca1a1310a8",
  "entity_type": "list",
  "data": {},
  "progress": 0,
  "status": "pending",
  "created_at": "2025-06-13T15:09:31.311Z",
  "updated_at": "2025-06-13T15:09:31.311Z"
}