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": "019dc79a-6a7c-7df7-8e62-6c27cc9781fd",
      "timestamp_created": "2026-04-26T02:24:39.039Z",
      "timestamp_updated": "2026-04-26T02:24:39.039Z",
      "organization": "019dc79a-6a7f-7770-918b-3147ec3bb7a4",
      "status": 1,
      "email_open_count": 0,
      "email_reply_count": 0,
      "email_click_count": 0,
      "company_domain": "example.com",
      "status_summary": {
        "lastStep": {
          "from": "campaign",
          "stepID": "019dc79a-6a7f-7770-918b-31494092fa3a",
          "timestamp_executed": "2026-04-26T02:24:39.039Z"
        },
        "domain_complete": true
      },
      "campaign": "019dc79a-6a7f-7770-918b-31483d7301c3",
      "email": "example@example.com",
      "personalization": "Hello, how are you?",
      "website": "https://example.com",
      "last_name": "Doe",
      "first_name": "John",
      "company_name": "Example Inc.",
      "job_title": "Head of Growth",
      "phone": "+1234567890",
      "payload": {
        "firstName": "<string>",
        "lastName": "<string>",
        "companyName": "<string>",
        "jobTitle": "<string>",
        "website": "<string>",
        "phone": "<string>",
        "personalization": "<string>"
      },
      "status_summary_subseq": {
        "from": "campaign",
        "stepID": "019dc79a-6a7f-7770-918b-314ad45639e1",
        "timestampExecuted": "2026-04-26T02:24:39.039Z"
      },
      "last_step_from": "campaign",
      "last_step_id": "019dc79a-6a7f-7770-918b-314b1338163c",
      "last_step_timestamp_executed": "2026-04-26T02:24:39.039Z",
      "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": "019dc79a-6a7f-7770-918b-314c14c155e9",
      "verification_status": 1,
      "pl_value_lead": "High",
      "timestamp_added_subsequence": "2026-04-26T02:24:39.039Z",
      "timestamp_last_contact": "2026-04-26T02:24:39.039Z",
      "timestamp_last_open": "2026-04-26T02:24:39.039Z",
      "timestamp_last_reply": "2026-04-26T02:24:39.039Z",
      "timestamp_last_interest_change": "2026-04-26T02:24:39.039Z",
      "timestamp_last_click": "2026-04-26T02:24:39.039Z",
      "enrichment_status": 1,
      "list_id": "019dc79a-6a7f-7770-918b-314d1674b3d8",
      "last_contacted_from": "email",
      "uploaded_by_user": "019dc79a-6a7f-7770-918b-314e17ed9fca",
      "upload_method": "manual",
      "assigned_to": "019dc79a-6a80-7d15-b9d7-3f8d211af968",
      "is_website_visitor": true,
      "timestamp_last_touch": "2026-04-26T02:24:39.040Z",
      "esp_code": 1,
      "esg_code": 1
    }
  ],
  "next_starting_after": "019dc79a-c4bb-71e7-9e2e-c2712797eb01"
}

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:

"019dc79a-b5fe-75c1-88a7-2c9de253147d"

​
list_id
string<uuid>

List ID to filter leads

Example:

"019dc79a-b5fe-75c1-88a7-2c9e2442aa33"

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

"019dc79a-c4bb-71e7-9e2e-c26eacc744b8"

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

"019dc79a-c4bb-71e7-9e2e-c270e193bd00"

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

"019dc79a-c4bb-71e7-9e2e-c2712797eb01"