List leads

curl --request POST \
  --url https://api.instantly.ai/api/v2/leads/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

import requests

url = "https://api.instantly.ai/api/v2/leads/list"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://api.instantly.ai/api/v2/leads/list', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

HttpResponse<String> response = Unirest.post("https://api.instantly.ai/api/v2/leads/list")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.instantly.ai/api/v2/leads/list",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.instantly.ai/api/v2/leads/list"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "items": [
    {
      "id": "019f7ffb-a852-7360-8a3f-1f0f7d9a3514",
      "timestamp_created": "2026-07-20T14:43:46.900Z",
      "timestamp_updated": "2026-07-20T14:43:46.900Z",
      "organization": "019f7ffb-a854-70c0-aa49-d23fe12b49fa",
      "status": 1,
      "email_open_count": 0,
      "email_reply_count": 0,
      "email_click_count": 0,
      "company_domain": "example.com",
      "status_summary": {
        "lastStep": {
          "from": "campaign",
          "stepID": "019f7ffb-a854-70c0-aa49-d241f636efd2",
          "timestamp_executed": "2026-07-20T14:43:46.900Z"
        },
        "domain_complete": true
      },
      "campaign": "019f7ffb-a854-70c0-aa49-d240596fcd7a",
      "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": "019f7ffb-a854-70c0-aa49-d242316990f3",
        "timestampExecuted": "2026-07-20T14:43:46.900Z"
      },
      "last_step_from": "campaign",
      "last_step_id": "019f7ffb-a854-70c0-aa49-d243d8cd83ce",
      "last_step_timestamp_executed": "2026-07-20T14:43:46.900Z",
      "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": "019f7ffb-a854-70c0-aa49-d244d0550a2d",
      "verification_status": 1,
      "pl_value_lead": "High",
      "timestamp_added_subsequence": "2026-07-20T14:43:46.900Z",
      "timestamp_last_contact": "2026-07-20T14:43:46.900Z",
      "timestamp_last_open": "2026-07-20T14:43:46.900Z",
      "timestamp_last_reply": "2026-07-20T14:43:46.900Z",
      "timestamp_last_interest_change": "2026-07-20T14:43:46.900Z",
      "timestamp_last_click": "2026-07-20T14:43:46.900Z",
      "enrichment_status": 1,
      "list_id": "019f7ffb-a854-70c0-aa49-d245db2f08d8",
      "last_contacted_from": "email",
      "uploaded_by_user": "019f7ffb-a854-70c0-aa49-d24673c12abd",
      "upload_method": "manual",
      "assigned_to": "019f7ffb-a854-70c0-aa49-d2476f4a58c7",
      "is_website_visitor": true,
      "timestamp_last_touch": "2026-07-20T14:43:46.900Z",
      "esp_code": 1,
      "esg_code": 1
    }
  ],
  "next_starting_after": "019f7ffb-d8ec-7eb4-8cf8-1a782bc57512"
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "body must have required property 'name'"
}

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Missing Authorization header"
}

{
  "statusCode": 402,
  "error": "Payment Required",
  "message": "Workspace does not have an active paid plan"
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Resource not found"
}

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}

Lead

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

POST

api

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 '{}'

import requests

url = "https://api.instantly.ai/api/v2/leads/list"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://api.instantly.ai/api/v2/leads/list', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

HttpResponse<String> response = Unirest.post("https://api.instantly.ai/api/v2/leads/list")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.instantly.ai/api/v2/leads/list",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.instantly.ai/api/v2/leads/list"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "items": [
    {
      "id": "019f7ffb-a852-7360-8a3f-1f0f7d9a3514",
      "timestamp_created": "2026-07-20T14:43:46.900Z",
      "timestamp_updated": "2026-07-20T14:43:46.900Z",
      "organization": "019f7ffb-a854-70c0-aa49-d23fe12b49fa",
      "status": 1,
      "email_open_count": 0,
      "email_reply_count": 0,
      "email_click_count": 0,
      "company_domain": "example.com",
      "status_summary": {
        "lastStep": {
          "from": "campaign",
          "stepID": "019f7ffb-a854-70c0-aa49-d241f636efd2",
          "timestamp_executed": "2026-07-20T14:43:46.900Z"
        },
        "domain_complete": true
      },
      "campaign": "019f7ffb-a854-70c0-aa49-d240596fcd7a",
      "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": "019f7ffb-a854-70c0-aa49-d242316990f3",
        "timestampExecuted": "2026-07-20T14:43:46.900Z"
      },
      "last_step_from": "campaign",
      "last_step_id": "019f7ffb-a854-70c0-aa49-d243d8cd83ce",
      "last_step_timestamp_executed": "2026-07-20T14:43:46.900Z",
      "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": "019f7ffb-a854-70c0-aa49-d244d0550a2d",
      "verification_status": 1,
      "pl_value_lead": "High",
      "timestamp_added_subsequence": "2026-07-20T14:43:46.900Z",
      "timestamp_last_contact": "2026-07-20T14:43:46.900Z",
      "timestamp_last_open": "2026-07-20T14:43:46.900Z",
      "timestamp_last_reply": "2026-07-20T14:43:46.900Z",
      "timestamp_last_interest_change": "2026-07-20T14:43:46.900Z",
      "timestamp_last_click": "2026-07-20T14:43:46.900Z",
      "enrichment_status": 1,
      "list_id": "019f7ffb-a854-70c0-aa49-d245db2f08d8",
      "last_contacted_from": "email",
      "uploaded_by_user": "019f7ffb-a854-70c0-aa49-d24673c12abd",
      "upload_method": "manual",
      "assigned_to": "019f7ffb-a854-70c0-aa49-d2476f4a58c7",
      "is_website_visitor": true,
      "timestamp_last_touch": "2026-07-20T14:43:46.900Z",
      "esp_code": 1,
      "esg_code": 1
    }
  ],
  "next_starting_after": "019f7ffb-d8ec-7eb4-8cf8-1a782bc57512"
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "body must have required property 'name'"
}

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Missing Authorization header"
}

{
  "statusCode": 402,
  "error": "Payment Required",
  "message": "Workspace does not have an active paid plan"
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Resource not found"
}

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}

Authorizations

Authorization

string

header

required

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

Body

application/json

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:

"019f7ffb-ceff-7048-b850-7b90b9c95dfc"

list_id

string<uuid>

List ID to filter leads

Example:

"019f7ffb-ceff-7048-b850-7b915790e288"

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[]

Show child attributes

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:

"019f7ffb-d8ec-7eb4-8cf8-1a75cec40ffa"

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:

"019f7ffb-d8ec-7eb4-8cf8-1a7790f3a636"

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

Show child attributes

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:

"019f7ffb-d8ec-7eb4-8cf8-1a782bc57512"

Delete leads in bulk Get lead

⌘I

Overview

Getting Started

Guides

Resources

Schemas

List leads

Authorizations

Body

Response