Get Leads by List

curl --request GET \
  --url https://api.example.com/api/v1/entities/leads/list/{id} \
  --header 'Authorization: Bearer <token>'

[
  {
    "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/..."
    }
  }
]

GET

api

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>'

[
  {
    "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/..."
    }
  }
]

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.

leads

Lead[]

Array of lead objects (for person-type lists)

Show Lead object properties

string

required

Unique identifier (UUID) for the person

createdAt

string

ISO 8601 timestamp when the person was created. Can be null.

updatedAt

string

ISO 8601 timestamp when the person was last updated. Can be null.

firstName

string

required

Person’s first name

lastName

string

required

Person’s last name

jobTitle

string

Person’s current job title. Can be null.

city

string

Person’s city. Can be null.

postalCode

string

Person’s postal/zip code. Can be null.

country

string

Person’s country. Can be null.

linkedinUrl

string

Person’s LinkedIn profile URL. Can be null.

phones

string[]

Array of person’s phone numbers. Defaults to empty array.

emails

string[]

Array of person’s email addresses (lowercase). Defaults to empty array.

companyId

string

UUID of the associated company. Can be null.

seniority

string

Person’s seniority level (e.g., “Director”, “VP”). Can be null.

departments

string[]

Array of department names. Defaults to empty array.

subDepartments

string[]

Array of sub-department names. Defaults to empty array.

functions

string[]

Array of job functions. Defaults to empty array.

industry

string

Person’s industry. Can be null.

skills

string[]

Array of skills. Defaults to empty array.

birthDate

string

Person’s birth date in ISO 8601 format. Can be null.

leadOwnerId

string

User ID of the lead owner. Can be null.

baseProviderId

string

Internal provider identifier. Can be null.

bullhornId

number

Bullhorn CRM client contact ID. Can be null.

crmId

string

Generic CRM identifier. Can be null.

GDPR consent status. One of: “UNKNOWN”, “OPTOUT”. Defaults to “UNKNOWN”.

Source of consent information. Can be null.

Timestamp when consent was last updated. Can be null.

deletedAt

string

Soft delete timestamp. Can be null.

company

object

Associated company object. Can be null. Returns all company fields via database join.

Show Company object properties

string

required

Unique identifier (UUID) for the company

createdAt

string

ISO 8601 creation timestamp. Can be null.

updatedAt

string

ISO 8601 last update timestamp. Can be null.

name

string

required

Company name

description

string

Detailed company description. Can be null.

summary

string

Brief summary of the company. Can be null.

headcount

string

Employee count or range. Can be null.

industry

string

Company industry classification. Can be null.

phones

string[]

Array of company phone numbers.

linkedinUrl

string

Company LinkedIn profile URL. Can be null.

websiteUrl

string

Company website URL. Can be null.

domain

string

Company domain name. Can be null.

city

string

Headquarters city. Can be null.

postalCode

string

Headquarters postal/zip code. Can be null.

country

string

Headquarters country. Can be null.

logoUrl

string

URL to company logo image. Can be null.

legalName

string

Legal company name. Can be null.

foundedYear

number

Year the company was founded. Can be null.

revenue

string

Revenue range. Can be null.

baseProviderId

string

Base Provider ID. Can be null.

bullhornId

number

Bullhorn CRM client corporation ID. Can be null.

crmId

string

Generic CRM identifier. Can be null.

location

object

Detailed location information. Can be null.

clientContact

object

Bullhorn CRM client contact data. Can be null.

Show ClientContact object properties

number

Bullhorn client contact ID

tasks

object

Bullhorn tasks association data

taskObjects

array

Array of Bullhorn task objects with full task details

languages

array

Array of language objects with language and level properties.

educations

array

Array of education history objects.

workExperiences

array

Array of work experience objects.

certificates

array

Array of certificate objects.

linkedinProfile

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).

companies

Company[]

Array of company objects (for company-type lists)

Show Company object properties

string

required

Unique identifier (UUID) for the company

createdAt

string

ISO 8601 timestamp when the company was created. Can be null.

updatedAt

string

ISO 8601 timestamp when the company was last updated. Can be null.

name

string

required

Company name

description

string

Detailed company description. Can be null.

summary

string

Brief summary of the company. Can be null.

headcount

string

Employee count or range. Can be null.

industry

string

Company industry classification. Can be null.

phones

string[]

Array of company phone numbers. Defaults to empty array.

linkedinUrl

string

Company LinkedIn profile URL. Can be null.

websiteUrl

string

Company website URL. Can be null.

domain

string

Company domain name. Can be null.

city

string

Headquarters city. Can be null.

postalCode

string

Headquarters postal/zip code. Can be null.

country

string

Headquarters country. Can be null.

logoUrl

string

URL to company logo image. Can be null.

legalName

string

Official legal name of the company. Can be null.

foundedYear

number

Year the company was founded. Can be null.

revenue

string

Company revenue or revenue range. Can be null.

baseProviderId

string

Internal provider identifier. Can be null.

bullhornId

number

Bullhorn CRM client corporation ID. Can be null.

crmId

string

Generic CRM identifier. Can be null.

location

object

Detailed location information. Can be null.

Show Location object properties

headquarter

object

Headquarters location with continent, country, state, city, street, postalCode, rawAddress, and coordinates properties

locations

array

Array of additional office locations

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/..."
    }
  }
]

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 userIds array or admin status)
Based on the list’s type field:
- 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.

​Authentication

​Request

​Response

​Person-Type List Response

​Company-Type List Response

​Response Examples

​How It Works

​List Types

Authentication

Request

Response

Person-Type List Response

Company-Type List Response

Response Examples

How It Works

List Types