INinstantly
Lead

List leads

Changed on

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

post/api/v2/leads/list

Request

  • Base URL
    https://api.instantly.ai
  • URL
    https://api.instantly.ai/api/v2/leads/list
  • Auth
    HTTP bearer

Request body

searchstring

Search term matched against the lead's email and profile fields (first and last name, company, job title, and similar). Matches whole words, and the beginning of a field's value — "smith" finds "John Smith", "mith" does not. Provide campaign or list_id to also match inside values. Newly created or updated leads can take a few seconds to become searchable.

filterstring

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

campaignstring uuid

Campaign ID to filter leads

list_idstring uuid

List ID to filter leads

in_campaignboolean

Whether the lead is in a campaign

in_listboolean

Whether the lead is in a list

idsstring[]

Array of lead IDs to include

excluded_idsstring[]

Array of lead IDs to exclude

contactsstring[]

Array of emails the leads needs to have

limitinteger

The number of items to return

starting_afterstring

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.

organization_user_idsstring[]

Array of organization user IDs to filter leads

smart_view_idstring uuid

Smart view ID to filter leads

is_website_visitorboolean

Whether the lead is a website visitor

distinct_contactsboolean

Whether to return distinct contacts

enrichment_status1 | -1 | 11 | -2

Enrichment status to filter leads

esg_code'0' | '1' | '2' | '3' | '4' | 'all' | 'none'

ESG code to filter leads

Example request

{
  "search": "John Doe",
  "filter": "FILTER_VAL_CONTACTED",
  "campaign": "01a19e6f-792e-7a08-a176-5b90fc62a669",
  "list_id": "01a19e6f-792e-7a08-a176-5b919a81ec1e",
  "in_campaign": true,
  "in_list": true,
  "ids": [
    "01a19e6f-792e-7a08-a176-5b92e0d90be2"
  ],
  "queries": [
    {
      "actionType": "email-open",
      "values": {
        "occurrence-days": 1
      }
    }
  ],
  "excluded_ids": [
    "01a19e6f-792e-7a08-a176-5b93692b5fe5"
  ],
  "contacts": [
    "test@test.com"
  ],
  "limit": 10,
  "starting_after": "01a19e6f-892e-7dcc-b18c-2ed0fb9a966d",
  "organization_user_ids": [
    "01a19e6f-892f-79a9-af16-6e551b3d45b5"
  ],
  "smart_view_id": "01a19e6f-892f-79a9-af16-6e566311024d",
  "is_website_visitor": true,
  "distinct_contacts": true,
  "enrichment_status": 1,
  "esg_code": "1"
}

Response

The list of Lead

next_starting_afterstring

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 response

{
  "items": [
    {
      "id": "01a19e6f-2e41-7ba2-915b-2693d2af6ff5",
      "timestamp_created": "2026-11-02T22:44:08.900Z",
      "timestamp_updated": "2026-11-02T22:44:08.900Z",
      "organization": "01a19e6f-2e44-787e-88ad-76ff16913c4e",
      "campaign": "01a19e6f-2e44-787e-88ad-7700bc47e384",
      "status": 1,
      "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",
      "company_domain": "example.com",
      "status_summary": {
        "lastStep": {
          "from": "campaign",
          "stepID": "01a19e6f-2e44-787e-88ad-7701e119481a",
          "timestamp_executed": "2026-11-02T22:44:08.901Z"
        },
        "domain_complete": true
      },
      "payload": {
        "firstName": "John",
        "lastName": "Doe",
        "companyName": "Acme Corp",
        "jobTitle": "Head of Growth",
        "website": "https://example.com",
        "phone": "+1234567890",
        "personalization": "Hi {{first_name}}, I noticed you work at {{company_name}}..."
      },
      "status_summary_subseq": {
        "from": "campaign",
        "stepID": "01a19e6f-2e45-7a3f-9014-b1136fb77f0b",
        "timestampExecuted": "2026-11-02T22:44:08.901Z"
      },
      "last_step_from": "campaign",
      "last_step_id": "01a19e6f-2e45-7a3f-9014-b1147fda737b",
      "last_step_timestamp_executed": "2026-11-02T22:44:08.901Z",
      "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": "01a19e6f-2e45-7a3f-9014-b1159019ed98",
      "verification_status": 1,
      "pl_value_lead": "High",
      "timestamp_added_subsequence": "2026-11-02T22:44:08.901Z",
      "timestamp_last_contact": "2026-11-02T22:44:08.901Z",
      "timestamp_last_open": "2026-11-02T22:44:08.901Z",
      "timestamp_last_reply": "2026-11-02T22:44:08.901Z",
      "timestamp_last_interest_change": "2026-11-02T22:44:08.901Z",
      "timestamp_last_click": "2026-11-02T22:44:08.901Z",
      "enrichment_status": 1,
      "list_id": "01a19e6f-2e45-7a3f-9014-b1166500c9ac",
      "last_contacted_from": "email",
      "uploaded_by_user": "01a19e6f-2e45-7a3f-9014-b117d9ab88b2",
      "upload_method": "manual",
      "assigned_to": "01a19e6f-2e45-7a3f-9014-b11834e719d8",
      "is_website_visitor": true,
      "timestamp_last_touch": "2026-11-02T22:44:08.901Z",
      "esp_code": 1,
      "esg_code": 1
    }
  ],
  "next_starting_after": "01a19e6f-892f-79a9-af16-6e57895715cf"
}

Changes

  • c781051105a8Revision changes
    • warning

      added the new 0.00 enum value to the // response property for the response status