/

List lead list

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.

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

Lead List

A list used to store leads

idstring(uuid)read-onlyrequired

Unique identifier for the lead list

Example: "0197c0c0-eb38-7ffb-9d76-c78d9d8aec3b"

organization_idstring(uuid)read-onlyrequired

Organization ID that owns this lead list

Example: "0197c0c0-eb38-7ffb-9d76-c78e47f19c89"

namestringrequired

Name of the lead list

Example: "My Lead List"

timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the lead list was created

Example: "2025-06-30T12:12:38.072Z"

has_enrichment_tasknull or boolean

Whether this list runs the enrichment process on every added lead or not

Example: false

owned_bynull or string(uuid)

User ID of the owner of this lead list. Defaults to the user that created the list

Example: "0197c0c0-eb38-7ffb-9d76-c78fea5365b3"

{
  "id": "0197c0c0-eb38-7ffb-9d76-c78d9d8aec3b",
  "organization_id": "0197c0c0-eb38-7ffb-9d76-c78e47f19c89",
  "has_enrichment_task": false,
  "owned_by": "0197c0c0-eb38-7ffb-9d76-c78fea5365b3",
  "name": "My Lead List",
  "timestamp_created": "2025-06-30T12:12:38.072Z"
}

Create lead list

Request

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

Bodyapplication/jsonrequired

The Lead List to create

namestringrequired

Name of the lead list

Example: "My Lead List"

has_enrichment_taskboolean or null

Whether this list runs the enrichment process on every added lead or not

Example: false

owned_bystring or null(uuid)

User ID of the owner of this lead list. Defaults to the user that created the list

Example: "0197c0c0-eb38-7ffb-9d76-c78fea5365b3"

curl -i -X POST \
  https://api.instantly.ai/api/v2/lead-lists \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "My Lead List"
  }'

Responses

The Lead List

Bodyapplication/json

idstring(uuid)read-onlyrequired

Unique identifier for the lead list

Example: "0197c0c0-eb38-7ffb-9d76-c78d9d8aec3b"

organization_idstring(uuid)read-onlyrequired

Organization ID that owns this lead list

Example: "0197c0c0-eb38-7ffb-9d76-c78e47f19c89"

namestringrequired

Name of the lead list

Example: "My Lead List"

timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the lead list was created

Example: "2025-06-30T12:12:38.072Z"

has_enrichment_tasknull or boolean

Whether this list runs the enrichment process on every added lead or not

Example: false

owned_bynull or string(uuid)

User ID of the owner of this lead list. Defaults to the user that created the list

Example: "0197c0c0-eb38-7ffb-9d76-c78fea5365b3"

Response

application/json

{
  "id": "0197c0c0-eb38-7ffb-9d76-c78d9d8aec3b",
  "organization_id": "0197c0c0-eb38-7ffb-9d76-c78e47f19c89",
  "has_enrichment_task": false,
  "owned_by": "0197c0c0-eb38-7ffb-9d76-c78fea5365b3",
  "name": "My Lead List",
  "timestamp_created": "2025-06-30T12:12:38.072Z"
}

List lead list

Request

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

Query

limitinteger[ 1 .. 100 ]

The number of items to return

Example: limit=10

starting_afterstring

Example: starting_after=2025-03-07T00:00:00.000Z

has_enrichment_taskboolean

Example: has_enrichment_task=true

searchstring

Search by list name

Example: search=Summer 2025 List

curl -i -X GET \
  'https://api.instantly.ai/api/v2/lead-lists?has_enrichment_task=true&limit=10&search=Summer%202025%20List&starting_after=2025-03-07T00%3A00%3A00.000Z' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The list of Lead List

Bodyapplication/json

itemsArray of objects(Lead List)required

items[].idstring(uuid)read-onlyrequired

Unique identifier for the lead list

Example: "0197c0c0-eb38-7ffb-9d76-c78d9d8aec3b"

items[].organization_idstring(uuid)read-onlyrequired

Organization ID that owns this lead list

Example: "0197c0c0-eb38-7ffb-9d76-c78e47f19c89"

items[].namestringrequired

Name of the lead list

Example: "My Lead List"

items[].timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the lead list was created

Example: "2025-06-30T12:12:38.072Z"

items[].has_enrichment_tasknull or boolean

Whether this list runs the enrichment process on every added lead or not

Example: false

items[].owned_bynull or string(uuid)

User ID of the owner of this lead list. Defaults to the user that created the list

Example: "0197c0c0-eb38-7ffb-9d76-c78fea5365b3"

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: "0197c0c1-0563-7951-b728-bf8826bce212"

Response

application/json

{
  "items": [
    { … }
  ],
  "next_starting_after": "0197c0c1-0563-7951-b728-bf8826bce212"
}

Get lead list

Request

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

Path

idstring(uuid)required

The ID of the requested item

Example: 0197c0c1-0564-7429-a127-03af783e086d

curl -i -X GET \
  https://api.instantly.ai/api/v2/lead-lists/0197c0c1-0564-7429-a127-03af783e086d \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The requested Lead List

Bodyapplication/json

idstring(uuid)read-onlyrequired

Unique identifier for the lead list

Example: "0197c0c0-eb38-7ffb-9d76-c78d9d8aec3b"

organization_idstring(uuid)read-onlyrequired

Organization ID that owns this lead list

Example: "0197c0c0-eb38-7ffb-9d76-c78e47f19c89"

namestringrequired

Name of the lead list

Example: "My Lead List"

timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the lead list was created

Example: "2025-06-30T12:12:38.072Z"

has_enrichment_tasknull or boolean

Whether this list runs the enrichment process on every added lead or not

Example: false

owned_bynull or string(uuid)

User ID of the owner of this lead list. Defaults to the user that created the list

Example: "0197c0c0-eb38-7ffb-9d76-c78fea5365b3"

Response

application/json

{
  "id": "0197c0c0-eb38-7ffb-9d76-c78d9d8aec3b",
  "organization_id": "0197c0c0-eb38-7ffb-9d76-c78e47f19c89",
  "has_enrichment_task": false,
  "owned_by": "0197c0c0-eb38-7ffb-9d76-c78fea5365b3",
  "name": "My Lead List",
  "timestamp_created": "2025-06-30T12:12:38.072Z"
}

Patch lead list

Request

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

Path

idstring(uuid)required

The ID of the item to update

Example: 0197c0c1-0564-7429-a127-03b077180644

Bodyapplication/json

non-empty

has_enrichment_taskboolean or null

Whether this list runs the enrichment process on every added lead or not

Example: false

owned_bystring or null(uuid)

User ID of the owner of this lead list. Defaults to the user that created the list

Example: "0197c0c0-eb38-7ffb-9d76-c78fea5365b3"

namestring

Name of the lead list

Example: "My Lead List"

curl -i -X PATCH \
  https://api.instantly.ai/api/v2/lead-lists/0197c0c1-0564-7429-a127-03b077180644 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

The updated Lead List

Bodyapplication/json

idstring(uuid)read-onlyrequired

Unique identifier for the lead list

Example: "0197c0c0-eb38-7ffb-9d76-c78d9d8aec3b"

organization_idstring(uuid)read-onlyrequired

Organization ID that owns this lead list

Example: "0197c0c0-eb38-7ffb-9d76-c78e47f19c89"

namestringrequired

Name of the lead list

Example: "My Lead List"

timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the lead list was created

Example: "2025-06-30T12:12:38.072Z"

has_enrichment_tasknull or boolean

Whether this list runs the enrichment process on every added lead or not

Example: false

owned_bynull or string(uuid)

User ID of the owner of this lead list. Defaults to the user that created the list

Example: "0197c0c0-eb38-7ffb-9d76-c78fea5365b3"

Response

application/json

{
  "id": "0197c0c0-eb38-7ffb-9d76-c78d9d8aec3b",
  "organization_id": "0197c0c0-eb38-7ffb-9d76-c78e47f19c89",
  "has_enrichment_task": false,
  "owned_by": "0197c0c0-eb38-7ffb-9d76-c78fea5365b3",
  "name": "My Lead List",
  "timestamp_created": "2025-06-30T12:12:38.072Z"
}

Delete lead list

Request

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

Path

idstring(uuid)required

The ID of the item to delete

Example: 0197c0c1-0565-7991-b81d-a0cc624c3460

Bodyapplication/json

null

curl -i -X DELETE \
  https://api.instantly.ai/api/v2/lead-lists/0197c0c1-0565-7991-b81d-a0cc624c3460 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json'

Responses

The deleted Lead List

Bodyapplication/json

idstring(uuid)read-onlyrequired

Unique identifier for the lead list

Example: "0197c0c0-eb38-7ffb-9d76-c78d9d8aec3b"

organization_idstring(uuid)read-onlyrequired

Organization ID that owns this lead list

Example: "0197c0c0-eb38-7ffb-9d76-c78e47f19c89"

namestringrequired

Name of the lead list

Example: "My Lead List"

timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the lead list was created

Example: "2025-06-30T12:12:38.072Z"

has_enrichment_tasknull or boolean

Whether this list runs the enrichment process on every added lead or not

Example: false

owned_bynull or string(uuid)

User ID of the owner of this lead list. Defaults to the user that created the list

Example: "0197c0c0-eb38-7ffb-9d76-c78fea5365b3"

Response

application/json

{
  "id": "0197c0c0-eb38-7ffb-9d76-c78d9d8aec3b",
  "organization_id": "0197c0c0-eb38-7ffb-9d76-c78e47f19c89",
  "has_enrichment_task": false,
  "owned_by": "0197c0c0-eb38-7ffb-9d76-c78fea5365b3",
  "name": "My Lead List",
  "timestamp_created": "2025-06-30T12:12:38.072Z"
}

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