Instantly Lead API
A lead entity representing an individual lead
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/instantly-ai-lead-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Explorer Lead API
description: 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.
version: 2.0.0
servers:
- url: https://api.instantly.ai
description: Instantly API Server
security:
- ApiKeyAuth: []
tags:
- name: Lead
description: A lead entity representing an individual lead
x-group: Lead
paths:
/api/v2/leads:
post:
operationId: createLead
summary: Create lead
tags:
- Lead
description: 'Requires one of the following scopes: `leads:create`, `leads:all`, `all:create`, `all:all`'
requestBody:
content:
application/json:
schema:
title: CreateLead
description: 'When using `campaign`: The `email` field is required. When using `list_id`: The `email` field is optional, but at least one of the following must be provided: `email`, `first_name`, or `last_name`.'
type: object
properties:
campaign:
type:
- string
- 'null'
description: Campaign ID associated with the lead
format: uuid
example: 019ffad2-53a3-7590-935f-b48cddbf2d9e
email:
type:
- string
- 'null'
description: Email address of the lead
example: example@example.com
personalization:
type:
- string
- 'null'
description: Personalization of the lead
example: Hello, how are you?
website:
type:
- string
- 'null'
description: Website of the lead
example: https://example.com
last_name:
type:
- string
- 'null'
description: Last name of the lead
example: Doe
first_name:
type:
- string
- 'null'
description: First name of the lead
example: John
company_name:
type:
- string
- 'null'
description: Company name of the lead
example: Example Inc.
job_title:
type:
- string
- 'null'
description: Job title of the lead
example: Head of Growth
phone:
type:
- string
- 'null'
description: Phone number of the lead
example: '+1234567890'
lt_interest_status:
type: number
description: Lead interest status. It can be either a static value (check below), or a custom status interest value
enum:
- 1
- 2
- 3
- 4
- 0
- -1
- -2
- -3
- -4
x-enumDescriptions:
'0': Out of Office
'1': Interested
'2': Meeting Booked
'3': Meeting Completed
'4': Won
'-1': Not Interested
'-2': Wrong Person
'-3': Lost
'-4': No Show
example: 1
pl_value_lead:
type:
- string
- 'null'
description: Potential value of the lead
example: High
list_id:
type:
- string
- 'null'
description: List ID associated with the lead
format: uuid
example: 019ffad2-53a3-7590-935f-b491178cb297
assigned_to:
type:
- string
- 'null'
description: ID of the user assigned to the lead
format: uuid
example: 019ffad2-53a3-7590-935f-b4938179e96d
skip_if_in_workspace:
type: boolean
description: Whether to skip if the lead is already in the workspace.
example: true
skip_if_in_campaign:
type: boolean
description: Whether to skip if the lead is already in the campaign.
example: true
skip_if_in_list:
type: boolean
description: Whether to skip if the lead is already in the list.
example: true
blocklist_id:
type: string
format: uuid
description: The ID of the blocklist to check for the lead.
example: 019ffad2-9c48-7618-b387-b7a401aae5fc
verify_leads_for_lead_finder:
type: boolean
description: Whether to verify the leads for the lead finder.
example: true
verify_leads_on_import:
type: boolean
description: Whether to verify the leads on import.
example: true
custom_variables:
type: object
additionalProperties:
type:
- string
- number
- boolean
- 'null'
description: 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
required: []
additionalProperties: false
description: 'When using `campaign`: The `email` field is required. When using `list_id`: The `email` field is optional, but at least one of the following must be provided: `email`, `first_name`, or `last_name`.'
responses:
'200':
description: The Lead
content:
application/json:
schema:
$ref: '#/components/schemas/Lead'
'400':
description: Invalid request body (e.g. missing required fields, or invalid field values)
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 400
examples:
- 400
example: 400
error:
type: string
enum:
- Bad Request
examples:
- Bad Request
example: Bad Request
message:
type: string
examples:
- body must have required property 'name'
example: body must have required property 'name'
required:
- statusCode
- error
- message
'401':
description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 401
examples:
- 401
example: 401
error:
type: string
enum:
- Unauthorized
examples:
- Unauthorized
example: Unauthorized
message:
type: string
examples:
- Missing Authorization header
example: Missing Authorization header
required:
- statusCode
- error
- message
'402':
description: This request cannot be fulfilled because the workspace does not have an active paid plan
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 402
examples:
- 402
example: 402
error:
type: string
enum:
- Payment Required
examples:
- Payment Required
example: Payment Required
message:
type: string
examples:
- Workspace does not have an active paid plan
example: Workspace does not have an active paid plan
required:
- statusCode
- error
- message
'404':
description: The requested resource was not found
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 404
examples:
- 404
example: 404
error:
type: string
enum:
- Not Found
examples:
- Not Found
example: Not Found
message:
type: string
examples:
- Resource not found
example: Resource not found
required:
- statusCode
- error
- message
'429':
description: You have exceeded the rate limit. Please check the rate limit docs for more information.
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 429
examples:
- 429
example: 429
error:
type: string
enum:
- Too Many Requests
examples:
- Too Many Requests
example: Too Many Requests
message:
type: string
examples:
- Rate limit exceeded
example: Rate limit exceeded
required:
- statusCode
- error
- message
delete:
operationId: bulkDeleteLeads
summary: Delete leads in bulk
tags:
- Lead
description: 'Delete multiple leads from a campaign or list based on filters. You must provide either `campaign_id` or `list_id`. Optionally filter by status or specific IDs.
Requires one of the following scopes: `leads:delete`, `leads:all`, `all:delete`, `all:all`'
requestBody:
content:
application/json:
schema:
type: object
properties:
campaign_id:
type: string
format: uuid
description: The ID of the campaign to delete leads from. Required if `list_id` is not provided.
example: 019ffad2-9c4c-7079-b87c-ef3272fbbda1
list_id:
type: string
format: uuid
description: The ID of the list to delete leads from. Required if `campaign_id` is not provided.
example: 019ffad2-9c4c-7079-b87c-ef33fbdf5eac
status:
type: number
enum:
- 1
- 2
- 3
- -1
- -2
- -3
x-enumDescriptions:
'1': Active
'2': Paused
'3': Completed
'-1': Bounced
'-2': Unsubscribed
'-3': Skipped
description: Optional status filter. Only delete leads with this status.
example: 3
ids:
type: array
items:
type: string
format: uuid
example: 019ffad2-9c4c-7079-b87c-ef348efbb1c9
description: Optional array of specific lead IDs to delete. When provided, only these leads will be deleted from the specified campaign or list.
limit:
type: integer
minimum: 1
maximum: 10000
description: Maximum number of leads to delete. If not specified, all matching leads will be deleted.
example: 100
anyOf:
- required:
- campaign_id
- required:
- list_id
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
count:
type: integer
description: Number of leads successfully deleted.
example: 5
'401':
description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 401
examples:
- 401
example: 401
error:
type: string
enum:
- Unauthorized
examples:
- Unauthorized
example: Unauthorized
message:
type: string
examples:
- Missing Authorization header
example: Missing Authorization header
required:
- statusCode
- error
- message
'402':
description: This request cannot be fulfilled because the workspace does not have an active paid plan
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 402
examples:
- 402
example: 402
error:
type: string
enum:
- Payment Required
examples:
- Payment Required
example: Payment Required
message:
type: string
examples:
- Workspace does not have an active paid plan
example: Workspace does not have an active paid plan
required:
- statusCode
- error
- message
'404':
description: The requested resource was not found
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 404
examples:
- 404
example: 404
error:
type: string
enum:
- Not Found
examples:
- Not Found
example: Not Found
message:
type: string
examples:
- Resource not found
example: Resource not found
required:
- statusCode
- error
- message
'429':
description: You have exceeded the rate limit. Please check the rate limit docs for more information.
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 429
examples:
- 429
example: 429
error:
type: string
enum:
- Too Many Requests
examples:
- Too Many Requests
example: Too Many Requests
message:
type: string
examples:
- Rate limit exceeded
example: Rate limit exceeded
required:
- statusCode
- error
- message
/api/v2/leads/list:
post:
operationId: listLeads
summary: List leads
tags:
- Lead
description: '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. Results are ordered by each lead''s `id` field in ascending order (or by `contact` when distinct_contacts is true) so clients can paginate chronologically by reusing the cursor returned in `next_starting_after`. Leads created on or after October 15, 2025 respect this chronological ordering; older records may appear out of sequence when sorted by ID.
Requires one of the following scopes: `leads:read`, `leads:all`, `all:read`, `all:all`'
requestBody:
content:
application/json:
schema:
type: object
properties:
search:
type: string
description: A search string to search the leads against - can be First Name, Last Name, or Email
example: John Doe
filter:
type: string
x-enumDescriptions:
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
FILTER_LEAD_OUT_OF_OFFICE: Filter for leads out of office
FILTER_LEAD_WRONG_PERSON: Filter for wrong person leads
FILTER_LEAD_LOST: Filter for lost leads
FILTER_LEAD_NO_SHOW: Filter for no show leads
FILTER_LEAD_CUSTOM_LABEL_POSITIVE: Filter for leads with positive custom label
FILTER_LEAD_CUSTOM_LABEL_NEGATIVE: Filter for leads with negative custom label
FILTER_VAL_BOUNCED: Filter for bounced leads
FILTER_VAL_SKIPPED: Filter for skipped leads
FILTER_VAL_RISKY: Filter for risky leads
FILTER_VAL_INVALID: Filter for invalid leads
FILTER_VAL_VALID: Filter for valid leads
FILTER_VAL_IN_SUBSEQUENCE: Filter for leads in subsequence
FILTER_VAL_OPENED_NO_REPLY: Filter for leads with opened emails but no reply
FILTER_VAL_COMPLETED_NO_REPLY: Filter for leads with completed sequence but no reply
FILTER_VAL_NO_OPENS: Filter for leads with no opened emails
FILTER_VAL_REPLIED: Filter for leads that replied
FILTER_VAL_LINK_CLICKED: Filter for leads that clicked a link
description: Filter criteria for leads. For custom lead labels, use the `interest_status` field.
example: FILTER_VAL_CONTACTED
campaign:
type: string
format: uuid
description: Campaign ID to filter leads
example: 019ffad2-90b0-7d6d-b877-e244a0d3d2b2
list_id:
type: string
format: uuid
description: List ID to filter leads
example: 019ffad2-90b0-7d6d-b877-e24585b902a6
in_campaign:
type: boolean
description: Whether the lead is in a campaign
example: true
in_list:
type: boolean
description: Whether the lead is in a list
example: true
ids:
type: array
items:
type: string
format: uuid
example: 019ffad2-90b0-7d6d-b877-e246e5ba5796
description: Array of lead IDs to include
queries:
type: array
items:
type: object
required:
- actionType
- values
description: Smart view query to filter leads
properties:
actionType:
type: string
enum:
- reply
- email-open
- last-contacted
- link-click
- lead-status
- lead-status-change
example: email-open
values:
type: object
properties:
occurrence-days:
type: number
example: 1
occurrence-count:
type: object
properties:
condition:
type: string
enum:
- more
- less
- equal
example: more
count:
type: number
example: 1
lead-status:
type: object
properties:
status:
type: number
example: 1
condition:
type: string
enum:
- is
- is-not
example: is
example:
actionType: email-open
values:
occurrence-days: 1
excluded_ids:
type: array
items:
type: string
format: uuid
example: 019ffad2-90b0-7d6d-b877-e2478776f0c0
description: Array of lead IDs to exclude
contacts:
type: array
items:
type: string
format: email
example: test@test.com
description: Array of emails the leads needs to have
limit:
type: integer
minimum: 1
maximum: 100
description: The number of items to return
example: 10
starting_after:
type: string
description: Forward pagination cursor. When distinct_contacts is false, provide the `id` value from the last lead of the previous page; when true, provide the lead's email.
example: 019ffad2-9c48-7618-b387-b7a5991d1b2a
organization_user_ids:
type: array
items:
type: string
format: uuid
example: 019ffad2-9c48-7618-b387-b7a6d551ef2e
description: Array of organization user IDs to filter leads
smart_view_id:
type: string
format: uuid
description: Smart view ID to filter leads
example: 019ffad2-9c48-7618-b387-b7a7119afa1a
is_website_visitor:
type: boolean
description: Whether the lead is a website visitor
example: true
distinct_contacts:
type: boolean
description: Whether to return distinct contacts
example: true
enrichment_status:
type: number
enum:
- 1
- -1
- 11
- -2
x-enumDescriptions:
'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
description: Enrichment status to filter leads
example: 1
esg_code:
type: string
enum:
- '0'
- '1'
- '2'
- '3'
- '4'
- all
- none
x-enumDescriptions:
'0': In Queue
'1': Barracuda
'2': Mimecast
'3': Proofpoint
'4': Cisco
all: All
none: None
description: ESG code to filter leads
example: '1'
responses:
'200':
description: The list of Lead
content:
application/json:
schema:
type: object
properties:
items:
type: array
description: The list of Lead
items:
$ref: '#/components/schemas/Lead'
next_starting_after:
type: string
examples:
- 019ffad2-9c48-7618-b387-b7a889cb0c87
- '2026-08-13T11:12:14.408Z'
description: The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API
example: 019ffad2-9c48-7618-b387-b7a889cb0c87
additionalProperties: false
required:
- items
'400':
description: Invalid request body (e.g. missing required fields, or invalid field values)
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 400
examples:
- 400
example: 400
error:
type: string
enum:
- Bad Request
examples:
- Bad Request
example: Bad Request
message:
type: string
examples:
- body must have required property 'name'
example: body must have required property 'name'
required:
- statusCode
- error
- message
'401':
description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 401
examples:
- 401
example: 401
error:
type: string
enum:
- Unauthorized
examples:
- Unauthorized
example: Unauthorized
message:
type: string
examples:
- Missing Authorization header
example: Missing Authorization header
required:
- statusCode
- error
- message
'402':
description: This request cannot be fulfilled because the workspace does not have an active paid plan
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 402
examples:
- 402
example: 402
error:
type: string
enum:
- Payment Required
examples:
- Payment Required
example: Payment Required
message:
type: string
examples:
- Workspace does not have an active paid plan
example: Workspace does not have an active paid plan
required:
- statusCode
- error
- message
'404':
description: The requested resource was not found
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 404
examples:
- 404
example: 404
error:
type: string
enum:
- Not Found
examples:
# --- truncated at 32 KB (132 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/instantly-ai/refs/heads/main/openapi/instantly-ai-lead-api-openapi.yml