---
title: "List leads"
method: POST
path: "/api/v2/leads/list"
tags: ["Lead"]
---

# List leads

`POST /api/v2/leads/list`

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`

## Request body

- object
  - `search` string — A search string to search the leads against - can be First Name, Last Name, or Email
  - `filter` string — Filter criteria for leads. For custom lead labels, use the `interest_status` field.
  - `campaign` string, uuid — Campaign ID to filter leads
  - `list_id` string, uuid — List ID to filter leads
  - `in_campaign` boolean — Whether the lead is in a campaign
  - `in_list` boolean — Whether the lead is in a list
  - `ids` string[] — Array of lead IDs to include
  - `queries` object[]
    - `actionType` 'reply' | 'email-open' | 'last-contacted' | 'link-click' | 'lead-status' | 'lead-status-change', required
    - `values` object, required
      - `occurrence-days` number
      - `occurrence-count` object
        - `condition` 'more' | 'less' | 'equal'
        - `count` number
      - `lead-status` object
        - `status` number
        - `condition` 'is' | 'is-not'
  - `excluded_ids` string[] — Array of lead IDs to exclude
  - `contacts` string[] — Array of emails the leads needs to have
  - `limit` integer — The number of items to return
  - `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.
  - `organization_user_ids` string[] — Array of organization user IDs to filter leads
  - `smart_view_id` string, uuid — Smart view ID to filter leads
  - `is_website_visitor` boolean — Whether the lead is a website visitor
  - `distinct_contacts` boolean — Whether to return distinct contacts
  - `enrichment_status` 1 | -1 | 11 | -2 — Enrichment status to filter leads
  - `esg_code` '0' | '1' | '2' | '3' | '4' | 'all' | 'none' — ESG code to filter leads

## Response `200`

The list of Lead

- object
  - `items` Lead[], required — The list of Lead
    - `id` string, uuid, required — Unique identifier for the lead
    - `timestamp_created` string, date-time, required — Timestamp when the lead was created
    - `timestamp_updated` string, date-time, required — Timestamp when the lead was last updated
    - `organization` string, uuid, required — Organization ID associated with the lead
    - `campaign` string, uuid, nullable — Campaign ID associated with the lead
    - `status` 1 | 2 | 3 | -1 | -2 | -3, required — Status of the lead
    - `email` string, nullable — Email address of the lead
    - `personalization` string, nullable — Personalization of the lead
    - `website` string, nullable — Website of the lead
    - `last_name` string, nullable — Last name of the lead
    - `first_name` string, nullable — First name of the lead
    - `company_name` string, nullable — Company name of the lead
    - `job_title` string, nullable — Job title of the lead
    - `phone` string, nullable — Phone number of the lead
    - `email_open_count` number, required — Number of times the email was opened
    - `email_reply_count` number, required — Number of times the email was replied to
    - `email_click_count` number, required — Number of times the email was clicked
    - `company_domain` string, required — Company domain of the lead
    - `status_summary` object, required — Status summary of the lead
      - `lastStep` object
        - `from` string
        - `stepID` string
        - `timestamp_executed` string, date-time
      - `domain_complete` boolean
    - `payload` object, nullable — Lead custom variables. This object can contain any key, but the values have to be of type string, number, boolean, or null. We do NOT allow objects or arrays as values.
      - `firstName` string
      - `lastName` string
      - `companyName` string
      - `jobTitle` string
      - `website` string
      - `phone` string
      - `personalization` string
    - `status_summary_subseq` object — Subsequence status summary of the lead
      - `from` string
      - `stepID` string
      - `timestampExecuted` string, date-time
    - `last_step_from` string, nullable — Source of the last step
    - `last_step_id` string, uuid, nullable — ID of the last step
    - `last_step_timestamp_executed` string, date-time, nullable — Timestamp when the last step was executed
    - `email_opened_step` number, nullable — Last email step opened by the lead
    - `email_opened_variant` number, nullable — Last step variant opened by the lead
    - `email_replied_step` number, nullable — Last email step the lead has replied to
    - `email_replied_variant` number, nullable — Last step variant the lead has replied to
    - `email_clicked_step` number, nullable — Last email step the lead has clicked
    - `email_clicked_variant` number, nullable — Last step variant the lead has clicked
    - `lt_interest_status` 1 | 2 | 3 | 4 | 0 | -1 | -2 | -3 | -4 — Lead interest status. It can be either a static value (check below), or a custom status interest value
    - `subsequence_id` string, nullable — ID of the subsequence
    - `verification_status` 1 | -1 | -2 | -3 | -4 | 11 | 12 — Verification status of the lead
    - `pl_value_lead` string, nullable — Potential value of the lead
    - `timestamp_added_subsequence` string, date-time, nullable — Timestamp when the lead was added to the subsequence
    - `timestamp_last_contact` string, date-time, nullable — Timestamp of the last contact with the lead
    - `timestamp_last_open` string, date-time, nullable — Timestamp of the last email open
    - `timestamp_last_reply` string, date-time, nullable — Timestamp of the last email reply
    - `timestamp_last_interest_change` string, date-time, nullable — Timestamp of the last interest status change
    - `timestamp_last_click` string, date-time, nullable — Timestamp of the last email click
    - `enrichment_status` 1 | -1 | 11 | -2 — Enrichment status of the lead
    - `list_id` string, uuid, nullable — List ID associated with the lead
    - `last_contacted_from` string, nullable — Source of the last contact
    - `uploaded_by_user` string, uuid, nullable — ID of the user who uploaded the lead
    - `upload_method` 'manual' | 'api' | 'website-visitor' — Method used to upload the lead
    - `assigned_to` string, uuid, nullable — ID of the user assigned to the lead
    - `is_website_visitor` boolean, nullable — Indicates if the lead is a website visitor
    - `timestamp_last_touch` string, date-time, nullable — Timestamp of the last touch with the lead
    - `esp_code` 0 | 1 | 2 | 3 | 8 | 9 | 10 | 12 | 13 | 999 | 1000 — ESP code associated with the lead
    - `esg_code` 0 | 1 | 2 | 3 | 4 — ESG code associated with the 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

## Other responses

- `400` — Invalid request body (e.g. missing required fields, or invalid field values)
- `401` — This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
- `402` — This request cannot be fulfilled because the workspace does not have an active paid plan
- `404` — The requested resource was not found
- `429` — You have exceeded the rate limit. Please check the rate limit docs for more information.

---

[API](https://skmtc.net/instantly/apis/api-explorer.md) · [All operations](https://skmtc.net/instantly/apis/api-explorer/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/instantly/api-explorer/versions/378d1e253fe7/schema)