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

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

Operations

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

SuperSearch Enrichment

An enrichment can take different forms, such as email enrichment or LinkedIn enrichment. Leads may be imported from SuperSearch using the dedicated endpoint, or enriched directly within a list or campaign by attaching an enrichment to it.

Operations

SuperSearch Enrichment

idstringread-onlyrequired

Unique identifier for the enrichment

Example: "01234567-89ab-cdef-0123-456789abcdef"

organization_idstring(uuid)read-onlyrequired

Organization ID that created this enrichment

Example: "01234567-89ab-cdef-0123-456789abcdef"

resource_idstring(uuid)read-onlyrequired

Unique identifier for the entity to enrich leads into

Example: "01234567-89ab-cdef-0123-456789abcdef"

resource_typenumberread-onlyrequired

Type of the entity to enrich leads into

Enum Value	Description
1	Campaign
2	List

Example: 1

limitnull or number

The maximum number of leads to enrich

Example: 100

enrichment_payloadobject

Enrichment payload

auto_updatenull or boolean

Whether new leads added to the resource will be automatically enriched using these same settings

Example: true

skip_rows_without_emailnull or boolean

Whether the fully enriched profile enrichment will run even if we don't find an email

Example: true

in_progressnull or boolean

Whether the enrichment is in progress

Example: true

typestring

Enrichment type to add to the resource

Enum Value	Description
work_email_enrichment	Work Email Enrichment
fully_enriched_profile	LinkedIn Enrichment
email_verification	Email Verification
joblisting	Job Listing Enrichment
technologies	Technologies Enrichment
news	News Enrichment
funding	Funding Enrichment

Example: "email_verification"

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "limit": 100,
  "organization_id": "01234567-89ab-cdef-0123-456789abcdef",
  "enrichment_payload": {},
  "auto_update": true,
  "skip_rows_without_email": true,
  "in_progress": true,
  "type": "email_verification",
  "resource_id": "01234567-89ab-cdef-0123-456789abcdef",
  "resource_type": 1
}

Enrich leads from supersearch

Request

Add leads from SuperSearch to the list or the campaign and enrich them. A list is automatically created if no resource is provided.

Bodyapplication/jsonrequired

search_filtersobjectrequired

Search filters to find leads (required)

search_filters.locationsArray of objects or objects

search_filters.departmentArray of strings

Items Enum Value	Description
Engineering	Engineering
Finance & Administration	Finance & Administration
Human Resources	Human Resources
IT & IS	IT & IS
Marketing	Marketing
Operations	Operations
Sales	Sales
Support	Support
Other	Other

Example: ["Engineering"]

search_filters.levelArray of strings

Items Enum Value	Description
C-Level	C-Level
VP-Level	VP-Level
Director-Level	Director-Level
Manager-Level	Manager-Level
Staff	Staff
Entry level	Entry level
Mid-Senior level	Mid-Senior level
Director	Director
Associate	Associate
Owner	Owner

Example: ["Entry level"]

search_filters.employee_countArray of strings

Items Enum Value	Description
0 - 25	0 - 25
25 - 100	25 - 100
100 - 250	100 - 250
250 - 1000	250 - 1000
1K - 10K	1K - 10K
10K - 50K	10K - 50K
50K - 100K	50K - 100K
> 100K	100K

Example: ["0 - 25"]

search_filters.revenueArray of strings

Items Enum Value	Description
$0 - 1M	$0 - 1M
$1 - 10M	$1M - 10M
$10 - 50M	$10M - 50M
$50 - 100M	$50M - 100M
$100 - 250M	$100M - 250M
$250 - 500M	$250M - 500M
$500M - 1B	$500M - 1B
> $1B	$1B

Example: ["$1 - 10M"]

search_filters.newsArray of strings

Items Enum Value	Description
launches	Launches
expands_offices_to	Expands Offices To
hires	Hires
partners_with	Partners With
leaves	Leaves
receives_financing	Receives Financing
recognized_as	Recognized As
closes_offices_in	Closes Offices In
is_developing	Is Developing
has_issues_with	Has Issues With

Example: ["launches"]

search_filters.titleobject

search_filters.nameArray of strings

Names of the lead to include in the search

Example: ["John Doe"]

search_filters.company_nameobject

search_filters.look_alikestring

If set, the lead finder will find companies that are similar to the look-alike domain

Example: "google.com"

search_filters.keyword_filterobject

search_filters.industryobject

search_filters.domainsArray of strings

Example: ["google.com"]

search_filters.funding_typeArray of strings

Items Enum Value	Description
angel	Angel
seed	Seed
pre_seed	Pre-Seed
series_a	Series A
series_b	Series B
series_c	Series C
series_d	Series D
series_e	Series E
series_f	Series F
series_g	Series G

Example: ["angel"]

search_filters.skip_owned_leadsboolean

If set, the lead finder will skip leads that are owned by the user

Example: true

search_filters.show_one_lead_per_companyboolean

If set, the lead finder will show only one lead per company

Example: true

search_namestring

Name of the search

Example: "Tech CEOs in San Francisco"

work_email_enrichmentboolean

Enable work email enrichment

Example: true

fully_enriched_profileboolean

Enable LinkedIn profile enrichment

Example: true

resource_idstring(uuid)

ID of existing resource to add leads to

Example: "01234567-89ab-cdef-0123-456789abcdef"

resource_typenumber

Type of resource

Enum12

Example: 1

auto_updateboolean

Whether to auto-update new leads

Example: true

skip_rows_without_emailboolean

Whether to skip leads without email

Example: true

list_namestring

Name for new list if resource_id not provided

Example: "My List"

limitnumber[ 1 .. 1000000 ]

Maximum number of leads to import

Example: 100

curl -i -X POST \
  https://api.instantly.ai/api/v2/supersearch-enrichment/enrich-leads-from-supersearch \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "search_filters": {}
  }'

Responses

Default Response

Bodyapplication/json

idstringrequired

Unique identifier for the enrichment

Example: "01234567-89ab-cdef-0123-456789abcdef"

organization_idstring(uuid)required

Organization ID that created this enrichment

Example: "01234567-89ab-cdef-0123-456789abcdef"

resource_idstring(uuid)required

ID of the resource (list or campaign)

Example: "01234567-89ab-cdef-0123-456789abcdef"

search_filtersobject

The search filters used for enrichment

limitnumber

Maximum number of leads to import

Example: 100

list_namestring

Name of the list created

Example: "Supersearch List (22 Sep 2025)"

Response

application/json

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "organization_id": "01234567-89ab-cdef-0123-456789abcdef",
  "resource_id": "01234567-89ab-cdef-0123-456789abcdef",
  "search_filters": {},
  "limit": 100,
  "list_name": "Supersearch List (22 Sep 2025)"
}

Get enrichment for resource

Request

Get the enrichment for a specific resource

Path

resource_idstring(uuid)required

The ID of the list or campaign to retrieve the enrichment.

Example: 123e4567-e89b-12d3-a456-426614174000

curl -i -X GET \
  https://api.instantly.ai/api/v2/supersearch-enrichment/123e4567-e89b-12d3-a456-426614174000 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Default Response

Bodyapplication/json

resource_idstring(uuid)required

ID of the resource being enriched

Example: "01234567-89ab-cdef-0123-456789abcdef"

enrichment_payloadobjectnon-emptyrequired

Enrichment types

enrichment_payload.work_email_enrichmentboolean

Example: true

enrichment_payload.fully_enriched_profileboolean

Example: true

enrichment_payload.email_verificationboolean

Example: false

enrichment_payload.joblistingboolean

Example: true

enrichment_payload.technologiesboolean

Example: true

enrichment_payload.newsboolean

Example: true

enrichment_payload.fundingboolean

Example: true

in_progressboolean

Whether the enrichment is in progress

Example: false

existsboolean

Whether the enrichment exists

Example: true

Response

application/json

{
  "resource_id": "01234567-89ab-cdef-0123-456789abcdef",
  "in_progress": false,
  "exists": true,
  "enrichment_payload": {
    "work_email_enrichment": true,
    "fully_enriched_profile": true,
    "email_verification": false,
    "joblisting": true,
    "technologies": true,
    "news": true,
    "funding": true
  }
}

Create an enrichment

Request

Create an enrichment for a specific resource (list or campaign). This is the main endpoint for adding enrichments to resources. The enrichments are automatically run after creation.

Bodyapplication/jsonrequired

resource_idstring(uuid)required

Unique identifier for the resource (list or campaign)

Example: "01234567-89ab-cdef-0123-456789abcdef"

typestringrequired

Enrichment type to add to the resource

Enum Value	Description
work_email_enrichment	Work Email Enrichment
fully_enriched_profile	LinkedIn Enrichment
email_verification	Email Verification
joblisting	Job Listing Enrichment
technologies	Technologies Enrichment
news	News Enrichment
funding	Funding Enrichment

Example: "email_verification"

limitnumber[ 1 .. 50000 ]

Maximum number of leads to enrich.

Example: 100

filtersArray of objects

Filters to apply to the enrichment

curl -i -X POST \
  https://api.instantly.ai/api/v2/supersearch-enrichment \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "resource_id": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "email_verification"
  }'

Responses

Default Response

Bodyapplication/json

idstringrequired

Unique identifier for the enrichment

Example: "01234567-89ab-cdef-0123-456789abcdef"

organization_idstring(uuid)required

Organization ID that created this enrichment

Example: "01234567-89ab-cdef-0123-456789abcdef"

resource_idstring(uuid)required

Unique identifier for the entity to enrich leads into

Example: "01234567-89ab-cdef-0123-456789abcdef"

limitnumber

The maximum number of leads to enrich

Example: 100

enrichment_payloadobject

The enrichment configuration payload

Response

application/json

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "limit": 100,
  "organization_id": "01234567-89ab-cdef-0123-456789abcdef",
  "resource_id": "01234567-89ab-cdef-0123-456789abcdef",
  "enrichment_payload": {
    "joblisting": true,
    "email_verification": true,
    "work_email_enrichment": true,
    "fully_enriched_profile": true
  }
}

Update enrichment settings for resource

Request

Path

resource_idstring(uuid)required

Unique identifier for the resource (list or campaign)

Example: 01234567-89ab-cdef-0123-456789abcdef

Bodyapplication/json

auto_updateboolean

Whether new leads added to the resource will be automatically enriched

Example: true

skip_rows_without_emailboolean

Whether the fully enriched profile enrichment will run even if we don't find an email

Example: true

curl -i -X PATCH \
  https://api.instantly.ai/api/v2/supersearch-enrichment/01234567-89ab-cdef-0123-456789abcdef/settings \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

The requested SuperSearch Enrichment

Bodyapplication/json

idstringread-onlyrequired

Unique identifier for the enrichment

Example: "01234567-89ab-cdef-0123-456789abcdef"

organization_idstring(uuid)read-onlyrequired

Organization ID that created this enrichment

Example: "01234567-89ab-cdef-0123-456789abcdef"

resource_idstring(uuid)read-onlyrequired

Unique identifier for the entity to enrich leads into

Example: "01234567-89ab-cdef-0123-456789abcdef"

resource_typenumberread-onlyrequired

Type of the entity to enrich leads into

Enum Value	Description
1	Campaign
2	List

Example: 1

limitnull or number

The maximum number of leads to enrich

Example: 100

enrichment_payloadobject

Enrichment payload

auto_updatenull or boolean

Whether new leads added to the resource will be automatically enriched using these same settings

Example: true

skip_rows_without_emailnull or boolean

Whether the fully enriched profile enrichment will run even if we don't find an email

Example: true

in_progressnull or boolean

Whether the enrichment is in progress

Example: true

typestring

Enrichment type to add to the resource

Enum Value	Description
work_email_enrichment	Work Email Enrichment
fully_enriched_profile	LinkedIn Enrichment
email_verification	Email Verification
joblisting	Job Listing Enrichment
technologies	Technologies Enrichment
news	News Enrichment
funding	Funding Enrichment

Example: "email_verification"

Response

application/json

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "limit": 100,
  "organization_id": "01234567-89ab-cdef-0123-456789abcdef",
  "enrichment_payload": {},
  "auto_update": true,
  "skip_rows_without_email": true,
  "in_progress": true,
  "type": "email_verification",
  "resource_id": "01234567-89ab-cdef-0123-456789abcdef",
  "resource_type": 1
}

Create AI enrichment

Request

Bodyapplication/jsonrequired

resource_idstring(uuid)required

Id of the resource (list or campaign) to enrich

Example: "01234567-89ab-cdef-0123-456789abcdef"

output_columnstringrequired

Name of the column where the AI enrichment results will be stored

Example: "ai_generated_content"

resource_typenumberrequired

Type of the entity to enrich

Enum Value	Description
1	Campaign
2	List

Example: 2

model_versionstringrequired

Version of the AI model to use for enrichment. Different models have different capabilities, costs, and token limits.

Enum Value	Description
3.5	GPT-3.5 Turbo - OpenAI's standard model with good performance and low cost
gpt-5	GPT-5 is OpenAI’s most advanced model, offering major improvements in reasoning, code quality, and user experience.
gpt-5-mini	GPT-5 Mini is a compact version of GPT-5, designed to handle lighter-weight reasoning tasks.
gpt-5-nano	GPT-5-Nano is the smallest and fastest variant in the GPT-5 system, optimized for developer tools, rapid interactions, and ultra-low latency environments.
4.0	GPT-4 - OpenAI's advanced model with improved reasoning
gpt-4o	GPT-4o - OpenAI's optimized model with improved performance
o3	o3 is a well-rounded and powerful model across domains. It sets a new standard for math, science, coding, and visual reasoning tasks.
gpt-4.1	GPT-4.1 is a flagship large language model optimized for advanced instruction following, real-world software engineering, and long-context reasoning.
claude-3.7-sonnet	Claude 3.7 Sonnet - Anthropic's most capable model
claude-3.5-sonnet	Claude 3.5 Sonnet - Anthropic's balanced model

Example: "gpt-4o"

input_columnsArray of strings

List of column names to use as input data for the AI enrichment. These are the fields from your leads that will be used to generate content.

Example: ["first_name"]

use_instantly_accountboolean

When true, the enrichment will use Instantly's account for API calls. When false, it will use your own API keys configured in settings.

Example: true

overwriteboolean

When true, will overwrite existing values in the output column. When false, only empty fields will be enriched.

Example: false

auto_updateboolean

When true, new leads added to the campaign/list will be automatically enriched using these same settings.

Example: true

skip_leads_without_emailboolean

When true, leads without an email will be skipped.

Example: false

limitnumber[ 1 .. 1000000 ]

Maximum number of leads to enrich.

Example: 100

promptstring

Custom prompt to guide the AI enrichment. Use {{variables}} to reference input data. Only used when templateId is not provided.

Example: "Write a personalized email to {{first_name}} from {{company_name}} about our new product"

template_idnumber

ID of a predefined AI prompt template to use instead of a custom prompt. Templates are reusable prompt configurations.

Example: 123

statusnumber

Status of the job

Enum Value	Description
1	Job is pending processing
2	Job is currently being processed
3	Job has been completed successfully
4	Job processing failed

Example: 1

show_stateboolean

Whether to send the state of the enrichment

Example: true

filtersArray of objects

Example: [{"column_name":"email","type":1,"value":["test@test.com"]}]

curl -i -X POST \
  https://api.instantly.ai/api/v2/supersearch-enrichment/ai \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "resource_id": "01234567-89ab-cdef-0123-456789abcdef",
    "output_column": "ai_generated_content",
    "resource_type": 2,
    "model_version": "gpt-4o"
  }'

Responses

Default Response

Bodyapplication/json

resource_idstring(uuid)required

ID of the resource being enriched

Example: "01234567-89ab-cdef-0123-456789abcdef"

resource_typenumberrequired

Type of the resource (1 for Campaign, 2 for List)

Enum Value	Description
1	Campaign
2	List

Example: 1

output_columnstringrequired

Name of the column where results will be stored

Example: "ai_generated_content"

statusnumberrequired

Status of the enrichment job

Example: 1

model_versionstringrequired

AI model version used for enrichment

Example: "gpt-4o"

overwritebooleanrequired

Whether to overwrite existing data

Example: false

auto_updatebooleanrequired

Whether to auto-update new leads

Example: true

input_columnsArray of strings

Input columns used for enrichment

Example: ["first_name"]

limitnumber

Maximum number of leads to process

Example: 100

template_idnull or number

ID of the prompt template used

Example: 123

Response

application/json

{
  "resource_id": "01234567-89ab-cdef-0123-456789abcdef",
  "resource_type": 1,
  "output_column": "ai_generated_content",
  "status": 1,
  "model_version": "gpt-4o",
  "input_columns": [
    "first_name"
  ],
  "overwrite": false,
  "auto_update": true,
  "limit": 100,
  "template_id": 123
}

Get enrichment history

Request

Retrieve the enrichment history for a specific resource

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

Path

resource_idstring(uuid)required

ID of the resource to retrieve

Example: 123e4567-e89b-12d3-a456-426614174000

Query

offsetnumber

Example: offset=0

limitnumber

Example: limit=10

curl -i -X GET \
  'https://api.instantly.ai/api/v2/supersearch-enrichment/history/123e4567-e89b-12d3-a456-426614174000?limit=10&offset=0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Default Response

Bodyapplication/jsonArray [

property name*anyadditional property

]

Response

application/json

[
  {}
]

Run enrichment for resource

Request

Run all enrichments associated with a resource for a list of leads or for all the leads that haven't been enriched yet

Bodyapplication/jsonrequired

resource_idstring(uuid)required

The ID of the resource (list or campaign) to run enrichments for

Example: "123e4567-e89b-12d3-a456-426614174000"

lead_idsArray of strings[ 1 .. 10000 ] items

List of lead IDs to enrich (optional)

Example: ["123e4567-e89b-12d3-a456-426614174000"]

limitinteger

If set, only the first N leads will be enriched

Example: 10

curl -i -X POST \
  https://api.instantly.ai/api/v2/supersearch-enrichment/run \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "resource_id": "123e4567-e89b-12d3-a456-426614174000"
  }'

Responses

Default Response

Bodyapplication/json

idstring

The ID of the enrichment

Example: "123e4567-e89b-12d3-a456-426614174000"

resource_idstring

The ID of the resource (list or campaign) to enrich

Example: "123e4567-e89b-12d3-a456-426614174000"

enrichment_payloadobject

The payload of the enrichment

Response

application/json

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "resource_id": "123e4567-e89b-12d3-a456-426614174000",
  "enrichment_payload": {}
}

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

Webhook

A webhook subscription for receiving event notifications

Operations

Webhook Event

A webhook event that was sent or attempted to be sent

Operations

DFY Email Account Order

A Done-For-You email account order

Operations

API Explorer (2.0.0)

Analytics

Account

Campaign

Email

Email Verification

Lead List

Inbox Placement Test

Inbox Placement Analytics

Inbox Placement Blacklist & SpamAssassin Report

API Key

Account Campaign Mapping

Lead

Background Job

Custom Tag

Block List Entry

Lead Label

Workspace

SuperSearch Enrichment

SuperSearch Enrichment

Enrich leads from supersearch

RequestExpand all

Responses

Was this helpful?

Get enrichment for resource

Request

Responses

Was this helpful?

Create an enrichment

Request

Responses

Was this helpful?

Update enrichment settings for resource

Request

Responses

Was this helpful?

Create AI enrichment

Request

Responses

Was this helpful?

Get enrichment history

Request

Responses

Was this helpful?

Run enrichment for resource

Request

Responses

Was this helpful?

Workspace Group Member

Workspace Member

Campaign Subsequence

Audit Log

Webhook

Webhook Event

DFY Email Account Order

Schemas

Request