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

Account Campaign Mapping

Account Campaign Mapping

campaign_idstring(uuid)required
Example: "01959271-1f64-7d23-a573-18a9d6906d6b"
campaign_namestringrequired
Example: "Campaign Name"
timestamp_createdstringread-onlyrequired

Timestamp when the campaign was created

Example: "2025-03-14T02:17:22.020Z"
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": "01959271-1f64-7d23-a573-18a9d6906d6b",
  "campaign_name": "Campaign Name",
  "timestamp_created": "2025-03-14T02:17:22.020Z",
  "status": 1
}

Lead

A lead entity representing an individual lead

idstring(uuid)read-onlyrequired

Unique identifier for the lead

Example: "01959271-1ec7-785e-b53b-fc11bab8020a"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the lead was created

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

Timestamp when the lead was last updated

Example: "2025-03-14T02:17:21.863Z"
organizationstring(uuid)read-onlyrequired

Organization ID associated with the lead

Example: "01959271-1ec7-785e-b53b-fc12bf16457d"
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: "01959271-1ec7-785e-b53b-fc145a7832fc"
status_summary.​timestamp_executedstring(date-time)
Example: "2025-03-14T02:17:21.863Z"
campaignstring(uuid)

Campaign ID associated with the lead

Example: "01959271-1ec7-785e-b53b-fc130c32a4df"
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: "01959271-1ec7-785e-b53b-fc1673bbf6f1"
last_step_timestamp_executedstring(date-time)read-only

Timestamp when the last step was executed

Example: "2025-03-14T02:17:21.864Z"
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: "01959271-1ec8-7187-b2ca-56cf457d9c5b"
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:17:21.864Z"
timestamp_last_contactstring(date-time)read-only

Timestamp of the last contact with the lead

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

Timestamp of the last email open

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

Timestamp of the last email reply

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

Timestamp of the last interest status change

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

Timestamp of the last email click

Example: "2025-03-14T02:17:21.864Z"
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: "01959271-1ec8-7187-b2ca-56d02a0054fb"
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: "01959271-1ec8-7187-b2ca-56d1f282bfd7"
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: "01959271-1ec8-7187-b2ca-56d2eac4fe52"
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:17:21.864Z"
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": "01959271-1ec7-785e-b53b-fc11bab8020a",
  "timestamp_created": "2025-03-14T02:17:21.863Z",
  "timestamp_updated": "2025-03-14T02:17:21.863Z",
  "organization": "01959271-1ec7-785e-b53b-fc12bf16457d",
  "campaign": "01959271-1ec7-785e-b53b-fc130c32a4df",
  "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": "01959271-1ec7-785e-b53b-fc145a7832fc",
    "timestamp_executed": "2025-03-14T02:17:21.863Z"
  },
  "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": "01959271-1ec7-785e-b53b-fc155b739b37",
    "timestampExecuted": "2025-03-14T02:17:21.863Z"
  },
  "last_step_from": "campaign",
  "last_step_id": "01959271-1ec7-785e-b53b-fc1673bbf6f1",
  "last_step_timestamp_executed": "2025-03-14T02:17:21.864Z",
  "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": "01959271-1ec8-7187-b2ca-56cf457d9c5b",
  "verification_status": 1,
  "pl_value_lead": "High",
  "timestamp_added_subsequence": "2025-03-14T02:17:21.864Z",
  "timestamp_last_contact": "2025-03-14T02:17:21.864Z",
  "timestamp_last_open": "2025-03-14T02:17:21.864Z",
  "timestamp_last_reply": "2025-03-14T02:17:21.864Z",
  "timestamp_last_interest_change": "2025-03-14T02:17:21.864Z",
  "timestamp_last_click": "2025-03-14T02:17:21.864Z",
  "enrichment_status": 1,
  "list_id": "01959271-1ec8-7187-b2ca-56d02a0054fb",
  "last_contacted_from": "email",
  "uploaded_by_user": "01959271-1ec8-7187-b2ca-56d1f282bfd7",
  "upload_method": "manual",
  "assigned_to": "01959271-1ec8-7187-b2ca-56d2eac4fe52",
  "is_website_visitor": true,
  "timestamp_last_touch": "2025-03-14T02:17:21.864Z",
  "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: "01959271-1f77-7821-ad9f-a5e57e71f336"
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:17:22.039Z"
updated_atstringrequired

Timestamp when the job was last updated

Example: "2025-03-14T02:17:22.039Z"
user_idstring(uuid)read-only

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

Example: "01959271-1f77-7821-ad9f-a5e61c680f12"
entity_idstring(uuid)

The id of the entity that the job is related to

Example: "01959271-1f77-7821-ad9f-a5e7bf808269"
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": "01959271-1f77-7821-ad9f-a5e57e71f336",
  "user_id": "01959271-1f77-7821-ad9f-a5e61c680f12",
  "type": "move-leads",
  "entity_id": "01959271-1f77-7821-ad9f-a5e7bf808269",
  "entity_type": "list",
  "data": {},
  "progress": 0,
  "status": "pending",
  "created_at": "2025-03-14T02:17:22.039Z",
  "updated_at": "2025-03-14T02:17:22.039Z"
}