List Lead Lists
curl --request GET \
--url https://api.example.com/api/v1/entities/leadlists \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/api/v1/entities/leadlists"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.example.com/api/v1/entities/leadlists', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/entities/leadlists",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/entities/leadlists"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/entities/leadlists")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/entities/leadlists")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"icpId": "660e8400-e29b-41d4-a716-446655440001",
"name": "Q1 2024 Tech Startups",
"type": "person",
"startDate": "2024-01-01T00:00:00.000Z",
"endDate": "2024-03-31T23:59:59.000Z",
"personIds": ["lead_abc123", "lead_def456", "lead_ghi789"],
"companyIds": [],
"userIds": ["user_xyz789", "user_abc123"],
"createdAt": "2024-01-02T10:30:00.000Z",
"updatedAt": "2024-01-15T14:22:00.000Z"
},
{
"id": "550e8400-e29b-41d4-a716-446655440002",
"icpId": null,
"name": "Enterprise Accounts",
"type": "company",
"startDate": "2024-02-01T00:00:00.000Z",
"endDate": "2024-06-30T23:59:59.000Z",
"personIds": [],
"companyIds": ["770e8400-e29b-41d4-a716-446655440001", "770e8400-e29b-41d4-a716-446655440002"],
"userIds": ["user_xyz789"],
"createdAt": "2024-02-01T09:00:00.000Z",
"updatedAt": "2024-02-10T11:45:00.000Z"
}
]
{
"error": {
"code": "UNAUTHORIZED",
"message": "Unauthorized"
}
}
Lead Lists
List Lead Lists
Retrieves all lead lists accessible to the authenticated user
GET
/
api
/
v1
/
entities
/
leadlists
List Lead Lists
curl --request GET \
--url https://api.example.com/api/v1/entities/leadlists \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/api/v1/entities/leadlists"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.example.com/api/v1/entities/leadlists', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/entities/leadlists",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/entities/leadlists"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/entities/leadlists")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/entities/leadlists")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"icpId": "660e8400-e29b-41d4-a716-446655440001",
"name": "Q1 2024 Tech Startups",
"type": "person",
"startDate": "2024-01-01T00:00:00.000Z",
"endDate": "2024-03-31T23:59:59.000Z",
"personIds": ["lead_abc123", "lead_def456", "lead_ghi789"],
"companyIds": [],
"userIds": ["user_xyz789", "user_abc123"],
"createdAt": "2024-01-02T10:30:00.000Z",
"updatedAt": "2024-01-15T14:22:00.000Z"
},
{
"id": "550e8400-e29b-41d4-a716-446655440002",
"icpId": null,
"name": "Enterprise Accounts",
"type": "company",
"startDate": "2024-02-01T00:00:00.000Z",
"endDate": "2024-06-30T23:59:59.000Z",
"personIds": [],
"companyIds": ["770e8400-e29b-41d4-a716-446655440001", "770e8400-e29b-41d4-a716-446655440002"],
"userIds": ["user_xyz789"],
"createdAt": "2024-02-01T09:00:00.000Z",
"updatedAt": "2024-02-10T11:45:00.000Z"
}
]
{
"error": {
"code": "UNAUTHORIZED",
"message": "Unauthorized"
}
}
Retrieves a list of all lead lists that the currently authenticated user has access to. Lead lists are collections of leads (persons or companies) organized for sales prospecting campaigns.
Authentication
This endpoint requires authentication. The user must be signed in to access lead lists.Users can only see lead lists they have been granted access to via the
userIds field. Admin users can see all lead lists in the organization.Request
This endpoint does not require any query parameters or request body.Response
Returns an array of lead list objects.array
An array of lead list objects accessible to the user.
Show Lead list object properties
Show Lead list object properties
string (UUID)
required
Unique identifier for the lead list.
string (UUID) | null
required
The ID of the Ideal Customer Profile (ICP) associated with this lead list. May be
null if not linked to an ICP.string
required
The display name of the lead list.
string
required
The type of leads in this list. Either
"person" for individual contacts or "company" for company leads.string
required
ISO 8601 timestamp indicating the start date of the lead list campaign.
string
required
ISO 8601 timestamp indicating the end date of the lead list campaign.
array
required
Array of person/lead IDs included in this list (when
type is "person").array
required
Array of company IDs included in this list (when
type is "company").array
required
Array of Clerk user IDs that have access to this lead list.
string
required
ISO 8601 timestamp of when the lead list was created.
string
required
ISO 8601 timestamp of when the lead list was last updated.
Response Examples
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"icpId": "660e8400-e29b-41d4-a716-446655440001",
"name": "Q1 2024 Tech Startups",
"type": "person",
"startDate": "2024-01-01T00:00:00.000Z",
"endDate": "2024-03-31T23:59:59.000Z",
"personIds": ["lead_abc123", "lead_def456", "lead_ghi789"],
"companyIds": [],
"userIds": ["user_xyz789", "user_abc123"],
"createdAt": "2024-01-02T10:30:00.000Z",
"updatedAt": "2024-01-15T14:22:00.000Z"
},
{
"id": "550e8400-e29b-41d4-a716-446655440002",
"icpId": null,
"name": "Enterprise Accounts",
"type": "company",
"startDate": "2024-02-01T00:00:00.000Z",
"endDate": "2024-06-30T23:59:59.000Z",
"personIds": [],
"companyIds": ["770e8400-e29b-41d4-a716-446655440001", "770e8400-e29b-41d4-a716-446655440002"],
"userIds": ["user_xyz789"],
"createdAt": "2024-02-01T09:00:00.000Z",
"updatedAt": "2024-02-10T11:45:00.000Z"
}
]
{
"error": {
"code": "UNAUTHORIZED",
"message": "Unauthorized"
}
}
Error Codes
| Status Code | Error Code | Description |
|---|---|---|
| 401 | UNAUTHORIZED | User is not authenticated. Ensure a valid session exists. |
| 500 | INTERNAL_ERROR | An unexpected server error occurred. |