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": "01a082d0-26bc-7045-ab14-65dfb4816106",
"timestamp_created": "2026-09-08T20:57:54.622Z",
"timestamp_updated": "2026-09-08T20:57:54.622Z",
"organization": "01a082d0-26be-7833-828f-7b1c3a259ece",
"status": 1,
"email_open_count": 0,
"email_reply_count": 0,
"email_click_count": 0,
"company_domain": "example.com",
"status_summary": {
"lastStep": {
"from": "campaign",
"stepID": "01a082d0-26be-7833-828f-7b1e925217d8",
"timestamp_executed": "2026-09-08T20:57:54.622Z"
},
"domain_complete": true
},
"campaign": "01a082d0-26be-7833-828f-7b1d15c4307e",
"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": "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": "01a082d0-26be-7833-828f-7b1f4b47df39",
"timestampExecuted": "2026-09-08T20:57:54.622Z"
},
"last_step_from": "campaign",
"last_step_id": "01a082d0-26be-7833-828f-7b20653477fc",
"last_step_timestamp_executed": "2026-09-08T20:57:54.622Z",
"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": "01a082d0-26be-7833-828f-7b21433b3e01",
"verification_status": 1,
"pl_value_lead": "High",
"timestamp_added_subsequence": "2026-09-08T20:57:54.622Z",
"timestamp_last_contact": "2026-09-08T20:57:54.622Z",
"timestamp_last_open": "2026-09-08T20:57:54.622Z",
"timestamp_last_reply": "2026-09-08T20:57:54.622Z",
"timestamp_last_interest_change": "2026-09-08T20:57:54.622Z",
"timestamp_last_click": "2026-09-08T20:57:54.623Z",
"enrichment_status": 1,
"list_id": "01a082d0-26bf-751b-9c73-8e1a3f2feb5c",
"last_contacted_from": "email",
"uploaded_by_user": "01a082d0-26bf-751b-9c73-8e1beaa75200",
"upload_method": "manual",
"assigned_to": "01a082d0-26bf-751b-9c73-8e1c97222895",
"is_website_visitor": true,
"timestamp_last_touch": "2026-09-08T20:57:54.623Z",
"esp_code": 1,
"esg_code": 1
}
],
"next_starting_after": "01a082d0-8427-7390-b3ca-456e2e8d7c4c"
}{
"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"
}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
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": "01a082d0-26bc-7045-ab14-65dfb4816106",
"timestamp_created": "2026-09-08T20:57:54.622Z",
"timestamp_updated": "2026-09-08T20:57:54.622Z",
"organization": "01a082d0-26be-7833-828f-7b1c3a259ece",
"status": 1,
"email_open_count": 0,
"email_reply_count": 0,
"email_click_count": 0,
"company_domain": "example.com",
"status_summary": {
"lastStep": {
"from": "campaign",
"stepID": "01a082d0-26be-7833-828f-7b1e925217d8",
"timestamp_executed": "2026-09-08T20:57:54.622Z"
},
"domain_complete": true
},
"campaign": "01a082d0-26be-7833-828f-7b1d15c4307e",
"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": "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": "01a082d0-26be-7833-828f-7b1f4b47df39",
"timestampExecuted": "2026-09-08T20:57:54.622Z"
},
"last_step_from": "campaign",
"last_step_id": "01a082d0-26be-7833-828f-7b20653477fc",
"last_step_timestamp_executed": "2026-09-08T20:57:54.622Z",
"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": "01a082d0-26be-7833-828f-7b21433b3e01",
"verification_status": 1,
"pl_value_lead": "High",
"timestamp_added_subsequence": "2026-09-08T20:57:54.622Z",
"timestamp_last_contact": "2026-09-08T20:57:54.622Z",
"timestamp_last_open": "2026-09-08T20:57:54.622Z",
"timestamp_last_reply": "2026-09-08T20:57:54.622Z",
"timestamp_last_interest_change": "2026-09-08T20:57:54.622Z",
"timestamp_last_click": "2026-09-08T20:57:54.623Z",
"enrichment_status": 1,
"list_id": "01a082d0-26bf-751b-9c73-8e1a3f2feb5c",
"last_contacted_from": "email",
"uploaded_by_user": "01a082d0-26bf-751b-9c73-8e1beaa75200",
"upload_method": "manual",
"assigned_to": "01a082d0-26bf-751b-9c73-8e1c97222895",
"is_website_visitor": true,
"timestamp_last_touch": "2026-09-08T20:57:54.623Z",
"esp_code": 1,
"esg_code": 1
}
],
"next_starting_after": "01a082d0-8427-7390-b3ca-456e2e8d7c4c"
}{
"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
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
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.
"John Doe"
Filter criteria for leads. For custom lead labels, use the interest_status field.
"FILTER_VAL_CONTACTED"
Campaign ID to filter leads
"01a082d0-759f-7935-9c83-edf4f1081ece"
List ID to filter leads
"01a082d0-759f-7935-9c83-edf5ee85d6e8"
Whether the lead is in a campaign
true
Whether the lead is in a list
true
Array of lead IDs to include
Show child attributes
Show child attributes
Array of lead IDs to exclude
Array of emails the leads needs to have
The number of items to return
1 <= x <= 10010
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.
"01a082d0-8427-7390-b3ca-456b6e843000"
Array of organization user IDs to filter leads
Smart view ID to filter leads
"01a082d0-8427-7390-b3ca-456d5927f817"
Whether the lead is a website visitor
true
Whether to return distinct contacts
true
Enrichment status to filter leads
1, -1, 11, -2 1
ESG code to filter leads
0, 1, 2, 3, 4, all, none "1"
Response
The list of Lead
The list of Lead
Show child attributes
Show child attributes
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
"01a082d0-8427-7390-b3ca-456e2e8d7c4c"
"2026-09-08T20:58:18.535Z"