Get Lead List
curl --request GET \
--url https://api.example.com/api/v1/entities/leadlists/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/api/v1/entities/leadlists/{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/leadlists/{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/leadlists/{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/leadlists/{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/leadlists/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/entities/leadlists/{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": "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"],
"companyIds": [],
"userIds": ["user_xyz789"],
"createdAt": "2024-01-02T10:30:00.000Z",
"updatedAt": "2024-01-02T10:30:00.000Z",
"persons": [
{
"id": "lead_abc123",
"firstName": "Jane",
"lastName": "Doe",
"jobTitle": "VP of Engineering",
"seniority": "VP",
"emails": ["jane.doe@techstartup.com"],
"phones": ["+1-555-123-4567"],
"city": "San Francisco",
"country": "United States",
"linkedinUrl": "https://www.linkedin.com/in/janedoe",
"company": {
"id": "comp_789",
"name": "Tech Startup Inc",
"industry": "Software",
"headcount": "51-200",
"city": "San Francisco",
"country": "United States"
},
"clientContact": {
"id": 12345,
"tasks": { "data": [] },
"taskObjects": []
}
}
]
}
{
"id": "770e8400-e29b-41d4-a716-446655440002",
"icpId": null,
"name": "Enterprise Accounts Q2",
"type": "company",
"startDate": "2024-04-01T00:00:00.000Z",
"endDate": "2024-06-30T23:59:59.000Z",
"personIds": [],
"companyIds": ["880e8400-e29b-41d4-a716-446655440003"],
"userIds": ["user_xyz789"],
"createdAt": "2024-03-15T14:00:00.000Z",
"updatedAt": "2024-03-15T14:00:00.000Z",
"companies": [
{
"id": "880e8400-e29b-41d4-a716-446655440003",
"name": "Enterprise Corp",
"industry": "Financial Services",
"headcount": "1001-5000",
"revenue": "$100M-$500M",
"city": "New York",
"country": "United States",
"websiteUrl": "https://enterprisecorp.com",
"linkedinUrl": "https://www.linkedin.com/company/enterprisecorp",
"logoUrl": "https://logo.clearbit.com/enterprisecorp.com"
}
]
}
{
"error": {
"code": "NOT_FOUND",
"message": "LeadList with id 'invalid-id' not found"
}
}
Lead Lists
Get Lead List
Retrieves a single lead list by ID with populated persons or companies
GET
/
api
/
v1
/
entities
/
leadlists
/
{id}
Get Lead List
curl --request GET \
--url https://api.example.com/api/v1/entities/leadlists/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/api/v1/entities/leadlists/{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/leadlists/{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/leadlists/{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/leadlists/{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/leadlists/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/entities/leadlists/{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": "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"],
"companyIds": [],
"userIds": ["user_xyz789"],
"createdAt": "2024-01-02T10:30:00.000Z",
"updatedAt": "2024-01-02T10:30:00.000Z",
"persons": [
{
"id": "lead_abc123",
"firstName": "Jane",
"lastName": "Doe",
"jobTitle": "VP of Engineering",
"seniority": "VP",
"emails": ["jane.doe@techstartup.com"],
"phones": ["+1-555-123-4567"],
"city": "San Francisco",
"country": "United States",
"linkedinUrl": "https://www.linkedin.com/in/janedoe",
"company": {
"id": "comp_789",
"name": "Tech Startup Inc",
"industry": "Software",
"headcount": "51-200",
"city": "San Francisco",
"country": "United States"
},
"clientContact": {
"id": 12345,
"tasks": { "data": [] },
"taskObjects": []
}
}
]
}
{
"id": "770e8400-e29b-41d4-a716-446655440002",
"icpId": null,
"name": "Enterprise Accounts Q2",
"type": "company",
"startDate": "2024-04-01T00:00:00.000Z",
"endDate": "2024-06-30T23:59:59.000Z",
"personIds": [],
"companyIds": ["880e8400-e29b-41d4-a716-446655440003"],
"userIds": ["user_xyz789"],
"createdAt": "2024-03-15T14:00:00.000Z",
"updatedAt": "2024-03-15T14:00:00.000Z",
"companies": [
{
"id": "880e8400-e29b-41d4-a716-446655440003",
"name": "Enterprise Corp",
"industry": "Financial Services",
"headcount": "1001-5000",
"revenue": "$100M-$500M",
"city": "New York",
"country": "United States",
"websiteUrl": "https://enterprisecorp.com",
"linkedinUrl": "https://www.linkedin.com/company/enterprisecorp",
"logoUrl": "https://logo.clearbit.com/enterprisecorp.com"
}
]
}
{
"error": {
"code": "NOT_FOUND",
"message": "LeadList with id 'invalid-id' not found"
}
}
Retrieves a lead list by its unique identifier. The response includes the lead list metadata along with fully populated person or company objects, depending on the list type.
Authentication
This endpoint requires authentication. Any authenticated user can retrieve lead lists.The response automatically populates
persons or companies based on the
list’s type field. Person-type lists return hydrated person objects with
their associated company and Bullhorn client contact data.Request
string (UUID)
required
The unique identifier of the lead list to retrieve.
Response
Returns the lead list with populated items (persons or companies depending on list type).Base Fields
string (UUID)
required
Unique identifier for the lead list.
string (UUID) | null
required
The ID of the associated Ideal Customer Profile, or
null if not linked.string
required
The display name of the lead list.
string
required
The type of leads in this list. Either
"person" or "company".string
required
ISO 8601 timestamp for the campaign start date.
string
required
ISO 8601 timestamp for the campaign end date.
array
required
Array of person/lead IDs stored in the list.
array
required
Array of company UUIDs stored in the list.
array
required
Array of user IDs with 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.
Populated Fields
array | undefined
Populated when
type is "person". Array of fully hydrated person objects
with nested company and Bullhorn client contact data. Each person object
includes: - id, firstName, lastName - Basic identity - jobTitle,
seniority - Professional details - emails, phones - Contact informationcity,country,postalCode- Location -linkedinUrl- LinkedIn profile URL -company- Nested company object (if associated) -clientContact- Nested Bullhorn client contact with tasks (if synced)
array | undefined
Populated when
type is "company". Array of company objects. Each company
object includes: - id, name, legalName - Identity - description,
summary - Company details - industry, headcount, revenue - Business
metrics - city, country, postalCode - Location - websiteUrl,
linkedinUrl, domain - Web presence - logoUrl - Company logo - phones -
Contact numbersResponse 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"],
"companyIds": [],
"userIds": ["user_xyz789"],
"createdAt": "2024-01-02T10:30:00.000Z",
"updatedAt": "2024-01-02T10:30:00.000Z",
"persons": [
{
"id": "lead_abc123",
"firstName": "Jane",
"lastName": "Doe",
"jobTitle": "VP of Engineering",
"seniority": "VP",
"emails": ["jane.doe@techstartup.com"],
"phones": ["+1-555-123-4567"],
"city": "San Francisco",
"country": "United States",
"linkedinUrl": "https://www.linkedin.com/in/janedoe",
"company": {
"id": "comp_789",
"name": "Tech Startup Inc",
"industry": "Software",
"headcount": "51-200",
"city": "San Francisco",
"country": "United States"
},
"clientContact": {
"id": 12345,
"tasks": { "data": [] },
"taskObjects": []
}
}
]
}
{
"id": "770e8400-e29b-41d4-a716-446655440002",
"icpId": null,
"name": "Enterprise Accounts Q2",
"type": "company",
"startDate": "2024-04-01T00:00:00.000Z",
"endDate": "2024-06-30T23:59:59.000Z",
"personIds": [],
"companyIds": ["880e8400-e29b-41d4-a716-446655440003"],
"userIds": ["user_xyz789"],
"createdAt": "2024-03-15T14:00:00.000Z",
"updatedAt": "2024-03-15T14:00:00.000Z",
"companies": [
{
"id": "880e8400-e29b-41d4-a716-446655440003",
"name": "Enterprise Corp",
"industry": "Financial Services",
"headcount": "1001-5000",
"revenue": "$100M-$500M",
"city": "New York",
"country": "United States",
"websiteUrl": "https://enterprisecorp.com",
"linkedinUrl": "https://www.linkedin.com/company/enterprisecorp",
"logoUrl": "https://logo.clearbit.com/enterprisecorp.com"
}
]
}
{
"error": {
"code": "NOT_FOUND",
"message": "LeadList with id 'invalid-id' not found"
}
}
Error Codes
| Status Code | Error Code | Description |
|---|---|---|
| 404 | NOT_FOUND | No lead list exists with the specified ID. |
| 500 | INTERNAL_ERROR | An unexpected server error occurred. |