Get Leads by List
curl --request GET \
--url https://api.example.com/api/v1/entities/leads/list/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/api/v1/entities/leads/list/{id}"
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/leads/list/{id}', 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/leads/list/{id}",
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/leads/list/{id}"
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/leads/list/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/entities/leads/list/{id}")
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": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-20T14:45:00.000Z",
"firstName": "John",
"lastName": "Smith",
"jobTitle": "Chief Technology Officer",
"city": "San Francisco",
"postalCode": "94102",
"country": "United States",
"linkedinUrl": "https://www.linkedin.com/in/johnsmith",
"phones": ["+1-555-123-4567"],
"emails": ["john.smith@acmecorp.com"],
"companyId": "550e8400-e29b-41d4-a716-446655440000",
"seniority": "C-Suite",
"departments": ["Engineering", "Technology"],
"subDepartments": [],
"functions": ["Technology"],
"industry": "Software",
"skills": ["Leadership", "Strategy", "Software Development"],
"baseProviderId": null,
"bullhornId": 98765,
"crmId": null,
"leadOwnerId": "user_abc123",
"consentStatus": "UNKNOWN",
"consentSource": null,
"consentUpdatedAt": null,
"deletedAt": null,
"company": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": "2024-01-10T08:00:00.000Z",
"updatedAt": "2024-01-18T12:30:00.000Z",
"name": "Acme Corporation",
"description": "A leading provider of innovative solutions...",
"summary": "Enterprise software company",
"headcount": "500-1000",
"industry": "Software",
"phones": ["+1-555-999-8888"],
"linkedinUrl": "https://www.linkedin.com/company/acme-corp",
"websiteUrl": "https://www.acmecorp.com",
"domain": "acmecorp.com",
"city": "San Francisco",
"postalCode": "94102",
"country": "United States",
"logoUrl": "https://logo.clearbit.com/acmecorp.com",
"legalName": "Acme Corporation Inc.",
"foundedYear": 2010,
"revenue": "$10M-$50M",
"baseProviderId": null,
"bullhornId": 12345,
"crmId": null,
"location": null
},
"clientContact": {
"id": 98765,
"tasks": {
"data": [
{ "id": 111 },
{ "id": 222 }
]
},
"taskObjects": [
{
"id": 111,
"subject": "Follow up call",
"status": "Not Started"
}
]
},
"languages": [
{ "language": "English", "level": "Native" }
],
"educations": [],
"workExperiences": [],
"certificates": [],
"linkedinProfile": {
"headline": "CTO at Acme Corporation",
"summary": "Passionate technology leader...",
"pictureUrl": "https://media.licdn.com/..."
}
}
]
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-20T14:45:00.000Z",
"name": "Acme Corporation",
"description": "A leading provider of innovative solutions...",
"summary": "Enterprise software company specializing in CRM solutions",
"headcount": "500-1000",
"industry": "Software",
"phones": ["+1-555-123-4567"],
"linkedinUrl": "https://www.linkedin.com/company/acme-corp",
"websiteUrl": "https://www.acmecorp.com",
"domain": "acmecorp.com",
"city": "San Francisco",
"postalCode": "94102",
"country": "United States",
"logoUrl": "https://logo.clearbit.com/acmecorp.com",
"legalName": "Acme Corporation Inc.",
"foundedYear": 2010,
"revenue": "$10M-$50M",
"baseProviderId": null,
"bullhornId": 12345,
"crmId": null,
"location": {
"headquarter": {
"continent": "North America",
"country": "United States",
"state": "California",
"city": "San Francisco",
"street": "123 Market Street",
"postalCode": "94102",
"rawAddress": "123 Market Street, San Francisco, CA 94102",
"coordinates": {
"lng": -122.4194,
"lat": 37.7749
}
},
"locations": []
}
}
]
[]
{
"error": {
"code": "FORBIDDEN",
"message": "User does not have access to this lead list"
}
}
{
"error": {
"code": "NOT_FOUND",
"message": "Lead list with id 'invalid-uuid' not found"
}
}
{
"error": {
"code": "UNAUTHORIZED",
"message": "Unauthorized"
}
}
{
"error": {
"code": "INTERNAL_ERROR",
"message": "An unexpected error occurred"
}
}
Lead Lists
Get Leads by List
Retrieve all leads (persons) or companies from a specific lead list by ID
GET
/
api
/
v1
/
entities
/
leads
/
list
/
{id}
Get Leads by List
curl --request GET \
--url https://api.example.com/api/v1/entities/leads/list/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/api/v1/entities/leads/list/{id}"
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/leads/list/{id}', 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/leads/list/{id}",
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/leads/list/{id}"
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/leads/list/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/entities/leads/list/{id}")
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": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-20T14:45:00.000Z",
"firstName": "John",
"lastName": "Smith",
"jobTitle": "Chief Technology Officer",
"city": "San Francisco",
"postalCode": "94102",
"country": "United States",
"linkedinUrl": "https://www.linkedin.com/in/johnsmith",
"phones": ["+1-555-123-4567"],
"emails": ["john.smith@acmecorp.com"],
"companyId": "550e8400-e29b-41d4-a716-446655440000",
"seniority": "C-Suite",
"departments": ["Engineering", "Technology"],
"subDepartments": [],
"functions": ["Technology"],
"industry": "Software",
"skills": ["Leadership", "Strategy", "Software Development"],
"baseProviderId": null,
"bullhornId": 98765,
"crmId": null,
"leadOwnerId": "user_abc123",
"consentStatus": "UNKNOWN",
"consentSource": null,
"consentUpdatedAt": null,
"deletedAt": null,
"company": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": "2024-01-10T08:00:00.000Z",
"updatedAt": "2024-01-18T12:30:00.000Z",
"name": "Acme Corporation",
"description": "A leading provider of innovative solutions...",
"summary": "Enterprise software company",
"headcount": "500-1000",
"industry": "Software",
"phones": ["+1-555-999-8888"],
"linkedinUrl": "https://www.linkedin.com/company/acme-corp",
"websiteUrl": "https://www.acmecorp.com",
"domain": "acmecorp.com",
"city": "San Francisco",
"postalCode": "94102",
"country": "United States",
"logoUrl": "https://logo.clearbit.com/acmecorp.com",
"legalName": "Acme Corporation Inc.",
"foundedYear": 2010,
"revenue": "$10M-$50M",
"baseProviderId": null,
"bullhornId": 12345,
"crmId": null,
"location": null
},
"clientContact": {
"id": 98765,
"tasks": {
"data": [
{ "id": 111 },
{ "id": 222 }
]
},
"taskObjects": [
{
"id": 111,
"subject": "Follow up call",
"status": "Not Started"
}
]
},
"languages": [
{ "language": "English", "level": "Native" }
],
"educations": [],
"workExperiences": [],
"certificates": [],
"linkedinProfile": {
"headline": "CTO at Acme Corporation",
"summary": "Passionate technology leader...",
"pictureUrl": "https://media.licdn.com/..."
}
}
]
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-20T14:45:00.000Z",
"name": "Acme Corporation",
"description": "A leading provider of innovative solutions...",
"summary": "Enterprise software company specializing in CRM solutions",
"headcount": "500-1000",
"industry": "Software",
"phones": ["+1-555-123-4567"],
"linkedinUrl": "https://www.linkedin.com/company/acme-corp",
"websiteUrl": "https://www.acmecorp.com",
"domain": "acmecorp.com",
"city": "San Francisco",
"postalCode": "94102",
"country": "United States",
"logoUrl": "https://logo.clearbit.com/acmecorp.com",
"legalName": "Acme Corporation Inc.",
"foundedYear": 2010,
"revenue": "$10M-$50M",
"baseProviderId": null,
"bullhornId": 12345,
"crmId": null,
"location": {
"headquarter": {
"continent": "North America",
"country": "United States",
"state": "California",
"city": "San Francisco",
"street": "123 Market Street",
"postalCode": "94102",
"rawAddress": "123 Market Street, San Francisco, CA 94102",
"coordinates": {
"lng": -122.4194,
"lat": 37.7749
}
},
"locations": []
}
}
]
[]
{
"error": {
"code": "FORBIDDEN",
"message": "User does not have access to this lead list"
}
}
{
"error": {
"code": "NOT_FOUND",
"message": "Lead list with id 'invalid-uuid' not found"
}
}
{
"error": {
"code": "UNAUTHORIZED",
"message": "Unauthorized"
}
}
{
"error": {
"code": "INTERNAL_ERROR",
"message": "An unexpected error occurred"
}
}
Returns the items contained in a lead list. The response type depends on the list’s
type field:
- For person-type lists: Returns an array of lead objects (persons with their associated company and CRM data)
- For company-type lists: Returns an array of company objects
Authentication
This endpoint requires authentication. The user must be signed in and have access to the requested lead list.Users can only access lead lists where their user ID is included in the list’s
userIds array, or if they are an admin user.Request
string
required
The unique identifier (UUID) of the lead list to retrieve
Response
The response structure varies based on the lead list type.Person-Type List Response
Returns an array of lead objects. Each lead is a person with their associated company and Bullhorn CRM data.Leads are filtered to only include those where the associated company has a
name. Leads without a valid company name are excluded from the response.
Lead[]
Array of lead objects (for person-type lists)
Show Lead object properties
Show Lead object properties
string
required
Unique identifier (UUID) for the person
string
ISO 8601 timestamp when the person was created. Can be null.
string
ISO 8601 timestamp when the person was last updated. Can be null.
string
required
Person’s first name
string
required
Person’s last name
string
Person’s current job title. Can be null.
string
Person’s city. Can be null.
string
Person’s postal/zip code. Can be null.
string
Person’s country. Can be null.
string
Person’s LinkedIn profile URL. Can be null.
string[]
Array of person’s phone numbers. Defaults to empty array.
string[]
Array of person’s email addresses (lowercase). Defaults to empty array.
string
UUID of the associated company. Can be null.
string
Person’s seniority level (e.g., “Director”, “VP”). Can be null.
string[]
Array of department names. Defaults to empty array.
string[]
Array of sub-department names. Defaults to empty array.
string[]
Array of job functions. Defaults to empty array.
string
Person’s industry. Can be null.
string[]
Array of skills. Defaults to empty array.
string
Person’s birth date in ISO 8601 format. Can be null.
string
User ID of the lead owner. Can be null.
string
Internal provider identifier. Can be null.
number
Bullhorn CRM client contact ID. Can be null.
string
Generic CRM identifier. Can be null.
string
GDPR consent status. One of: “UNKNOWN”, “OPTOUT”. Defaults to “UNKNOWN”.
string
Source of consent information. Can be null.
string
Timestamp when consent was last updated. Can be null.
string
Soft delete timestamp. Can be null.
object
Associated company object. Can be null. Returns all company fields via database join.
Show Company object properties
Show Company object properties
string
required
Unique identifier (UUID) for the company
string
ISO 8601 creation timestamp. Can be null.
string
ISO 8601 last update timestamp. Can be null.
string
required
Company name
string
Detailed company description. Can be null.
string
Brief summary of the company. Can be null.
string
Employee count or range. Can be null.
string
Company industry classification. Can be null.
string[]
Array of company phone numbers.
string
Company LinkedIn profile URL. Can be null.
string
Company website URL. Can be null.
string
Company domain name. Can be null.
string
Headquarters city. Can be null.
string
Headquarters postal/zip code. Can be null.
string
Headquarters country. Can be null.
string
URL to company logo image. Can be null.
string
Legal company name. Can be null.
number
Year the company was founded. Can be null.
string
Revenue range. Can be null.
string
Base Provider ID. Can be null.
number
Bullhorn CRM client corporation ID. Can be null.
string
Generic CRM identifier. Can be null.
object
Detailed location information. Can be null.
object
array
Array of language objects with
language and level properties.array
Array of education history objects.
array
Array of work experience objects.
array
Array of certificate objects.
object
LinkedIn profile data with
headline, summary, and pictureUrl properties. Can be null.Company-Type List Response
Returns an array of company objects (same structure as the Company object nested within leads).Company[]
Array of company objects (for company-type lists)
Show Company object properties
Show Company object properties
string
required
Unique identifier (UUID) for the company
string
ISO 8601 timestamp when the company was created. Can be null.
string
ISO 8601 timestamp when the company was last updated. Can be null.
string
required
Company name
string
Detailed company description. Can be null.
string
Brief summary of the company. Can be null.
string
Employee count or range. Can be null.
string
Company industry classification. Can be null.
string[]
Array of company phone numbers. Defaults to empty array.
string
Company LinkedIn profile URL. Can be null.
string
Company website URL. Can be null.
string
Company domain name. Can be null.
string
Headquarters city. Can be null.
string
Headquarters postal/zip code. Can be null.
string
Headquarters country. Can be null.
string
URL to company logo image. Can be null.
string
Official legal name of the company. Can be null.
number
Year the company was founded. Can be null.
string
Company revenue or revenue range. Can be null.
string
Internal provider identifier. Can be null.
number
Bullhorn CRM client corporation ID. Can be null.
string
Generic CRM identifier. Can be null.
Response Examples
[
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-20T14:45:00.000Z",
"firstName": "John",
"lastName": "Smith",
"jobTitle": "Chief Technology Officer",
"city": "San Francisco",
"postalCode": "94102",
"country": "United States",
"linkedinUrl": "https://www.linkedin.com/in/johnsmith",
"phones": ["+1-555-123-4567"],
"emails": ["john.smith@acmecorp.com"],
"companyId": "550e8400-e29b-41d4-a716-446655440000",
"seniority": "C-Suite",
"departments": ["Engineering", "Technology"],
"subDepartments": [],
"functions": ["Technology"],
"industry": "Software",
"skills": ["Leadership", "Strategy", "Software Development"],
"baseProviderId": null,
"bullhornId": 98765,
"crmId": null,
"leadOwnerId": "user_abc123",
"consentStatus": "UNKNOWN",
"consentSource": null,
"consentUpdatedAt": null,
"deletedAt": null,
"company": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": "2024-01-10T08:00:00.000Z",
"updatedAt": "2024-01-18T12:30:00.000Z",
"name": "Acme Corporation",
"description": "A leading provider of innovative solutions...",
"summary": "Enterprise software company",
"headcount": "500-1000",
"industry": "Software",
"phones": ["+1-555-999-8888"],
"linkedinUrl": "https://www.linkedin.com/company/acme-corp",
"websiteUrl": "https://www.acmecorp.com",
"domain": "acmecorp.com",
"city": "San Francisco",
"postalCode": "94102",
"country": "United States",
"logoUrl": "https://logo.clearbit.com/acmecorp.com",
"legalName": "Acme Corporation Inc.",
"foundedYear": 2010,
"revenue": "$10M-$50M",
"baseProviderId": null,
"bullhornId": 12345,
"crmId": null,
"location": null
},
"clientContact": {
"id": 98765,
"tasks": {
"data": [
{ "id": 111 },
{ "id": 222 }
]
},
"taskObjects": [
{
"id": 111,
"subject": "Follow up call",
"status": "Not Started"
}
]
},
"languages": [
{ "language": "English", "level": "Native" }
],
"educations": [],
"workExperiences": [],
"certificates": [],
"linkedinProfile": {
"headline": "CTO at Acme Corporation",
"summary": "Passionate technology leader...",
"pictureUrl": "https://media.licdn.com/..."
}
}
]
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-20T14:45:00.000Z",
"name": "Acme Corporation",
"description": "A leading provider of innovative solutions...",
"summary": "Enterprise software company specializing in CRM solutions",
"headcount": "500-1000",
"industry": "Software",
"phones": ["+1-555-123-4567"],
"linkedinUrl": "https://www.linkedin.com/company/acme-corp",
"websiteUrl": "https://www.acmecorp.com",
"domain": "acmecorp.com",
"city": "San Francisco",
"postalCode": "94102",
"country": "United States",
"logoUrl": "https://logo.clearbit.com/acmecorp.com",
"legalName": "Acme Corporation Inc.",
"foundedYear": 2010,
"revenue": "$10M-$50M",
"baseProviderId": null,
"bullhornId": 12345,
"crmId": null,
"location": {
"headquarter": {
"continent": "North America",
"country": "United States",
"state": "California",
"city": "San Francisco",
"street": "123 Market Street",
"postalCode": "94102",
"rawAddress": "123 Market Street, San Francisco, CA 94102",
"coordinates": {
"lng": -122.4194,
"lat": 37.7749
}
},
"locations": []
}
}
]
[]
{
"error": {
"code": "FORBIDDEN",
"message": "User does not have access to this lead list"
}
}
{
"error": {
"code": "NOT_FOUND",
"message": "Lead list with id 'invalid-uuid' not found"
}
}
{
"error": {
"code": "UNAUTHORIZED",
"message": "Unauthorized"
}
}
{
"error": {
"code": "INTERNAL_ERROR",
"message": "An unexpected error occurred"
}
}
How It Works
- The endpoint authenticates the user via Clerk
- Retrieves the lead list by the provided ID
- Validates the user has access to the list (via
userIdsarray or admin status) - Based on the list’s
typefield:- Person lists: Fetches all persons with their associated company and Bullhorn CRM data (including tasks), filters to only include leads with a valid company name
- Company lists: Fetches all companies by their IDs from the list
- Returns the appropriate array of items
For person-type lists, the response includes Bullhorn CRM integration data
when available. The
clientContact object contains the Bullhorn client
contact record and associated tasks, enabling CRM workflow visibility directly
from the lead list.List Types
Lead lists can be one of two types:| Type | Description | Response Contains |
|---|---|---|
person | Contains individual leads/contacts | Array of Lead objects with company data |
company | Contains target companies | Array of Company objects |
The list type is set when the list is created and determines how the list is
populated and what data is returned.