Skip to main content
POST
/
api
/
v2
/
leads
/
list
List leads
curl --request POST \
  --url https://api.instantly.ai/api/v2/leads/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
{
  "items": [
    {
      "id": "019cc043-9cfe-773d-89ef-f0307b5667de",
      "timestamp_created": "2026-03-05T23:09:42.527Z",
      "timestamp_updated": "2026-03-05T23:09:42.527Z",
      "organization": "019cc043-9cff-7f4c-88ba-3c161f82ff62",
      "status": 1,
      "email_open_count": 0,
      "email_reply_count": 0,
      "email_click_count": 0,
      "company_domain": "example.com",
      "status_summary": {
        "lastStep": {
          "from": "campaign",
          "stepID": "019cc043-9d00-75e0-9e83-1926965ab998",
          "timestamp_executed": "2026-03-05T23:09:42.528Z"
        },
        "domain_complete": true
      },
      "campaign": "019cc043-9cff-7f4c-88ba-3c17864ea05e",
      "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",
      "payload": {
        "firstName": "<string>",
        "lastName": "<string>",
        "companyName": "<string>",
        "website": "<string>",
        "phone": "<string>",
        "personalization": "<string>"
      },
      "status_summary_subseq": {
        "from": "campaign",
        "stepID": "019cc043-9d00-75e0-9e83-192783c224fa",
        "timestampExecuted": "2026-03-05T23:09:42.528Z"
      },
      "last_step_from": "campaign",
      "last_step_id": "019cc043-9d00-75e0-9e83-1928c6e5d52f",
      "last_step_timestamp_executed": "2026-03-05T23:09:42.528Z",
      "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": "019cc043-9d00-75e0-9e83-1929decb0201",
      "verification_status": 1,
      "pl_value_lead": "High",
      "timestamp_added_subsequence": "2026-03-05T23:09:42.528Z",
      "timestamp_last_contact": "2026-03-05T23:09:42.528Z",
      "timestamp_last_open": "2026-03-05T23:09:42.528Z",
      "timestamp_last_reply": "2026-03-05T23:09:42.528Z",
      "timestamp_last_interest_change": "2026-03-05T23:09:42.528Z",
      "timestamp_last_click": "2026-03-05T23:09:42.528Z",
      "enrichment_status": 1,
      "list_id": "019cc043-9d00-75e0-9e83-192ac690b675",
      "last_contacted_from": "email",
      "uploaded_by_user": "019cc043-9d00-75e0-9e83-192b93c3ac43",
      "upload_method": "manual",
      "assigned_to": "019cc043-9d00-75e0-9e83-192cca9a643e",
      "is_website_visitor": true,
      "timestamp_last_touch": "2026-03-05T23:09:42.528Z",
      "esp_code": 1,
      "esg_code": 1
    }
  ],
  "next_starting_after": "019cc043-e397-7dfa-a912-4ff300057f58"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
search
string

A search string to search the leads against - can be First Name, Last Name, or Email

Example:

"John Doe"

​
filter
string

Filter criteria for leads. For custom lead labels, use the interest_status field.

Example:

"FILTER_VAL_CONTACTED"

​
campaign
string<uuid>

Campaign ID to filter leads

Example:

"019cc043-d74d-7eae-885a-00dbd6697052"

​
list_id
string<uuid>

List ID to filter leads

Example:

"019cc043-d74d-7eae-885a-00dcbf3b1304"

​
in_campaign
boolean

Whether the lead is in a campaign

Example:

true

​
in_list
boolean

Whether the lead is in a list

Example:

true

​
ids
string<uuid>[]

Array of lead IDs to include

​
queries
object[]
​
excluded_ids
string<uuid>[]

Array of lead IDs to exclude

​
contacts
string<email>[]

Array of emails the leads needs to have

​
limit
integer

The number of items to return

Required range: 1 <= x <= 100
Example:

10

​
starting_after
string

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:

"019cc043-e397-7dfa-a912-4ff0a05e5fe9"

​
organization_user_ids
string<uuid>[]

Array of organization user IDs to filter leads

​
smart_view_id
string<uuid>

Smart view ID to filter leads

Example:

"019cc043-e397-7dfa-a912-4ff20fd50b7d"

​
is_website_visitor
boolean

Whether the lead is a website visitor

Example:

true

​
distinct_contacts
boolean

Whether to return distinct contacts

Example:

true

​
enrichment_status
enum<number>

Enrichment status to filter leads

Available options:
1,
-1,
11,
-2
Example:

1

​
esg_code
enum<string>

ESG code to filter leads

Available options:
0,
1,
2,
3,
4,
all,
none
Example:

"1"

Response

The list of Lead

​
items
Lead · object[]
required

The list of Lead

​
next_starting_after
string

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:

"019cc043-e397-7dfa-a912-4ff300057f58"