Skip to main content
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>'
{
  "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": []
      }
    }
  ]
}
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

​
id
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

​
id
string (UUID)
required
Unique identifier for the lead list.
​
icpId
string (UUID) | null
required
The ID of the associated Ideal Customer Profile, or null if not linked.
​
name
string
required
The display name of the lead list.
​
type
string
required
The type of leads in this list. Either "person" or "company".
​
startDate
string
required
ISO 8601 timestamp for the campaign start date.
​
endDate
string
required
ISO 8601 timestamp for the campaign end date.
​
personIds
array
required
Array of person/lead IDs stored in the list.
​
companyIds
array
required
Array of company UUIDs stored in the list.
​
userIds
array
required
Array of user IDs with access to this lead list.
​
createdAt
string
required
ISO 8601 timestamp of when the lead list was created.
​
updatedAt
string
required
ISO 8601 timestamp of when the lead list was last updated.

​
Populated Fields

​
persons
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 information
  • city, country, postalCode - Location - linkedinUrl - LinkedIn profile URL - company - Nested company object (if associated) - clientContact - Nested Bullhorn client contact with tasks (if synced)
​
companies
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 numbers

​
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"],
  "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": []
      }
    }
  ]
}

​
Error Codes

Status CodeError CodeDescription
404NOT_FOUNDNo lead list exists with the specified ID.
500INTERNAL_ERRORAn unexpected server error occurred.