> ## Documentation Index > Fetch the complete documentation index at: https://developer.instantly.ai/llms.txt > Use this file to discover all available pages before exploring further. # List leads > 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` ## OpenAPI ````yaml https://api.instantly.ai/openapi/api_v2.json post /api/v2/leads/list openapi: 3.1.0 info: title: API Explorer 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: Analytics description: Endpoints related to analytics x-displayName: Analytics - name: OAuth description: >- OAuth authentication endpoints for connecting Google and Microsoft email accounts x-displayName: OAuth - name: Account description: An email account that can be used to send campaigns x-displayName: Account - name: Campaign description: A campaign that can be sent to a list of recipients x-displayName: Campaign - name: Email description: >- A campaign email, a reply, a manually sent email, or any other email that's visible in the Unibox x-displayName: Email - name: EmailVerification description: A single email verification x-displayName: Email Verification - name: LeadList description: A list used to store leads x-displayName: Lead List - name: InboxPlacementTest description: An inbox placement test x-displayName: Inbox Placement Test - name: InboxPlacementAnalytics description: Analytics data for individual emails in inbox placement tests x-displayName: Inbox Placement Analytics - name: InboxPlacementBlacklist&SpamAssassinReport description: Report data for an inbox placement test x-displayName: Inbox Placement Blacklist & SpamAssassin Report - name: APIKey description: API Key x-displayName: API Key - name: AccountCampaignMapping description: Account Campaign Mapping x-displayName: Account Campaign Mapping - name: Lead description: A lead entity representing an individual lead x-displayName: Lead - name: BackgroundJob description: A background job that can be used to perform long-running tasks x-displayName: Background Job - name: CustomTag description: >- A custom tag for organizing and categorizing accounts and campaigns. You can use them as filters in apis that list accounts and campaigns. x-displayName: Custom Tag - name: CustomTagMapping description: >- This entity represents a tag being assigned to a specific campaign or email account. When an email account is assigned a tag, a new custom tag mapping entry is created, which connects the tag (`tag_id` field) with the email account (`resource_id` field). You can use it to see which tag si connected to which resource. x-displayName: Custom Tag Mapping - name: BlockListEntry description: A blocked email or domain x-displayName: Block List Entry - name: LeadLabel description: A custom label for categorizing and managing leads x-displayName: Lead Label - name: Workspace description: A workspace entity representing a workspace x-displayName: Workspace - name: SuperSearchEnrichment description: >- An enrichment can take different forms, such as email enrichment or LinkedIn enrichment. Leads may be imported from SuperSearch using the dedicated endpoint, or enriched directly within a list or campaign by attaching an enrichment to it. x-displayName: SuperSearch Enrichment - name: WorkspaceGroupMember description: >- A member of a workspace group. You can use the endpoints within this entity to manage the members of a workspace group. x-displayName: Workspace Group Member - name: WorkspaceMember description: A member of a workspace with associated user details x-displayName: Workspace Member - name: CampaignSubsequence description: A subsequence entity representing a follow-up sequence x-displayName: Campaign Subsequence - name: AuditLog description: Audit log records for tracking system activities x-displayName: Audit Log - name: Webhook description: A webhook subscription for receiving event notifications x-displayName: Webhook - name: WebhookEvent description: A webhook event that was sent or attempted to be sent x-displayName: Webhook Event - name: DFYEmailAccountOrder description: A Done-For-You email account order x-displayName: DFY Email Account Order - name: CustomPromptTemplate description: Custom prompt templates for creating custom prompts x-displayName: Custom Prompt Template - name: SalesFlow description: >- Manages how sales users view and interact with campaign and lead lists within the sales flow. x-displayName: Sales Flow - name: EmailTemplate description: A campaign email template x-displayName: Email Template - name: WorkspaceBilling description: Workspace Billing x-displayName: Workspace Billing - name: CRMActions description: CRM related actions x-displayName: CRM Actions paths: /api/v2/leads/list: post: tags: - Lead summary: List leads 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` operationId: listLeads 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: 019e18e2-9b9a-7ae7-a643-c22062035e92 list_id: type: string format: uuid description: List ID to filter leads example: 019e18e2-9b9a-7ae7-a643-c221e2cbb421 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: 019e18e2-9b9a-7ae7-a643-c222bc883f9b 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: 019e18e2-9b9a-7ae7-a643-c223f81b2b84 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: 019e18e2-a5de-74de-8b12-ab7d2d0bb58e organization_user_ids: type: array items: type: string format: uuid example: 019e18e2-a5de-74de-8b12-ab7e902045cf description: Array of organization user IDs to filter leads smart_view_id: type: string format: uuid description: Smart view ID to filter leads example: 019e18e2-a5de-74de-8b12-ab7f0903e8fa 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/def-11' next_starting_after: type: string 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: 019e18e2-a5de-74de-8b12-ab80ff143bae additionalProperties: false required: - items '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 example: 401 error: type: string enum: - Unauthorized example: Unauthorized message: type: string 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 example: 402 error: type: string enum: - Payment Required example: Payment Required message: type: string 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 example: 404 error: type: string enum: - Not Found example: Not Found message: type: string 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 example: 429 error: type: string enum: - Too Many Requests example: Too Many Requests message: type: string example: Rate limit exceeded required: - statusCode - error - message components: schemas: def-11: title: Lead description: A lead entity representing an individual lead x-tags: - Schemas - Lead type: object properties: id: type: string description: Unique identifier for the lead readOnly: true format: uuid example: 019e18e2-6487-73d2-a3b2-643e2207f444 timestamp_created: type: string description: Timestamp when the lead was created readOnly: true format: date-time example: '2026-05-11T21:12:30.601Z' timestamp_updated: type: string description: Timestamp when the lead was last updated readOnly: true format: date-time example: '2026-05-11T21:12:30.602Z' organization: type: string description: Organization ID associated with the lead readOnly: true format: uuid example: 019e18e2-648a-71b0-899a-91e1385efbab campaign: type: - 'null' - string description: Campaign ID associated with the lead format: uuid example: 019e18e2-648a-71b0-899a-91e277fed22b status: type: number description: Status of the lead readOnly: true enum: - 1 - 2 - 3 - -1 - -2 - -3 x-enumDescriptions: '1': Active '2': Paused '3': Completed '-1': Bounced '-2': Unsubscribed '-3': Skipped example: 1 email: type: - 'null' - string description: Email address of the lead example: example@example.com personalization: type: - 'null' - string description: Personalization of the lead example: Hello, how are you? website: type: - 'null' - string description: Website of the lead example: https://example.com last_name: type: - 'null' - string description: Last name of the lead example: Doe first_name: type: - 'null' - string description: First name of the lead example: John company_name: type: - 'null' - string description: Company name of the lead example: Example Inc. job_title: type: - 'null' - string description: Job title of the lead example: Head of Growth phone: type: - 'null' - string description: Phone number of the lead example: '+1234567890' email_open_count: type: number description: Number of times the email was opened readOnly: true example: 0 email_reply_count: type: number description: Number of times the email was replied to readOnly: true example: 0 email_click_count: type: number description: Number of times the email was clicked readOnly: true example: 0 company_domain: type: string description: Company domain of the lead readOnly: true example: example.com status_summary: type: object description: Status summary of the lead readOnly: true properties: lastStep: type: object properties: from: type: string example: campaign stepID: type: string example: 019e18e2-648a-71b0-899a-91e3e16b18a4 timestamp_executed: type: string format: date-time example: '2026-05-11T21:12:30.602Z' domain_complete: type: boolean example: true payload: type: - 'null' - object description: >- 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. readOnly: true properties: firstName: type: string examples: - John lastName: type: string examples: - Doe companyName: type: string examples: - Acme Corp jobTitle: type: string examples: - Head of Growth website: type: string examples: - https://example.com phone: type: string examples: - '+1234567890' personalization: type: string examples: - Hi {{first_name}}, I noticed you work at {{company_name}}... additionalProperties: type: - 'null' - string - number - boolean - object status_summary_subseq: type: object description: Subsequence status summary of the lead readOnly: true properties: from: type: string example: campaign stepID: type: string example: 019e18e2-648a-71b0-899a-91e4eb5ee45a timestampExecuted: type: string format: date-time example: '2026-05-11T21:12:30.602Z' last_step_from: type: - 'null' - string description: Source of the last step readOnly: true example: campaign last_step_id: type: - 'null' - string description: ID of the last step readOnly: true format: uuid example: 019e18e2-648a-71b0-899a-91e59c6fda4d last_step_timestamp_executed: type: - 'null' - string description: Timestamp when the last step was executed readOnly: true format: date-time example: '2026-05-11T21:12:30.602Z' email_opened_step: type: - 'null' - number description: Last email step opened by the lead readOnly: true example: 1 email_opened_variant: type: - 'null' - number description: Last step variant opened by the lead readOnly: true example: 1 email_replied_step: type: - 'null' - number description: Last email step the lead has replied to readOnly: true example: 1 email_replied_variant: type: - 'null' - number description: Last step variant the lead has replied to readOnly: true example: 1 email_clicked_step: type: - 'null' - number description: Last email step the lead has clicked readOnly: true example: 1 email_clicked_variant: type: - 'null' - number description: Last step variant the lead has clicked readOnly: true example: 1 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 subsequence_id: type: - 'null' - string description: ID of the subsequence readOnly: true example: 019e18e2-648a-71b0-899a-91e6245d709f verification_status: type: number description: Verification status of the lead readOnly: true enum: - 1 - -1 - -2 - -3 - -4 - 11 - 12 x-enumDescriptions: '1': Verified '11': Pending '12': Pending Verification Job '-1': Invalid '-2': Risky '-3': Catch All '-4': Job Change example: 1 pl_value_lead: type: - 'null' - string description: Potential value of the lead example: High timestamp_added_subsequence: type: - 'null' - string description: Timestamp when the lead was added to the subsequence readOnly: true format: date-time example: '2026-05-11T21:12:30.602Z' timestamp_last_contact: type: - 'null' - string description: Timestamp of the last contact with the lead readOnly: true format: date-time example: '2026-05-11T21:12:30.602Z' timestamp_last_open: type: - 'null' - string description: Timestamp of the last email open readOnly: true format: date-time example: '2026-05-11T21:12:30.602Z' timestamp_last_reply: type: - 'null' - string description: Timestamp of the last email reply readOnly: true format: date-time example: '2026-05-11T21:12:30.602Z' timestamp_last_interest_change: type: - 'null' - string description: Timestamp of the last interest status change readOnly: true format: date-time example: '2026-05-11T21:12:30.602Z' timestamp_last_click: type: - 'null' - string description: Timestamp of the last email click readOnly: true format: date-time example: '2026-05-11T21:12:30.602Z' enrichment_status: type: number description: Enrichment status of the lead readOnly: true enum: - 1 - -1 - 11 - -2 x-enumDescriptions: '1': Enriched '11': Pending '-1': Enrichment data not available '-2': Error example: 1 list_id: type: - 'null' - string description: List ID associated with the lead format: uuid example: 019e18e2-648a-71b0-899a-91e72b7b7036 last_contacted_from: type: - 'null' - string description: Source of the last contact readOnly: true example: email uploaded_by_user: type: - 'null' - string description: ID of the user who uploaded the lead readOnly: true format: uuid example: 019e18e2-648a-71b0-899a-91e8bf31f4dd upload_method: type: string description: Method used to upload the lead readOnly: true enum: - manual - api - website-visitor x-enumDescriptions: manual: Manual api: API website-visitor: Website Visitor example: manual assigned_to: type: - 'null' - string description: ID of the user assigned to the lead format: uuid example: 019e18e2-648a-71b0-899a-91e9616b0144 is_website_visitor: type: - 'null' - boolean description: Indicates if the lead is a website visitor readOnly: true example: true timestamp_last_touch: type: - 'null' - string description: Timestamp of the last touch with the lead readOnly: true format: date-time example: '2026-05-11T21:12:30.602Z' esp_code: type: number description: ESP code associated with the lead readOnly: true enum: - 0 - 1 - 2 - 3 - 8 - 9 - 10 - 12 - 13 - 999 - 1000 x-enumDescriptions: '0': In Queue '1': Google '2': Microsoft '3': Zoho '8': AirMail '9': Yahoo '10': Yandex '12': Web.de '13': Libero.it '999': Other '1000': Not Found example: 1 esg_code: type: number description: ESG code associated with the lead readOnly: true enum: - 0 - 1 - 2 - 3 - 4 x-enumDescriptions: '0': In Queue '1': Barracuda '2': Mimecast '3': Proofpoint '4': Cisco example: 1 required: - id - timestamp_created - timestamp_updated - organization - status - email_open_count - email_reply_count - email_click_count - company_domain - status_summary additionalProperties: false securitySchemes: ApiKeyAuth: type: http scheme: bearer ````