> ## Documentation Index > Fetch the complete documentation index at: https://docs.lance.so/llms.txt > Use this file to discover all available pages before exploring further. # Get Leads by List > Retrieve all leads (persons) or companies from a specific lead list by ID 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 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. Array of lead objects (for person-type lists) Unique identifier (UUID) for the person ISO 8601 timestamp when the person was created. Can be null. ISO 8601 timestamp when the person was last updated. Can be null. Person's first name Person's last name Person's current job title. Can be null. Person's city. Can be null. Person's postal/zip code. Can be null. Person's country. Can be null. Person's LinkedIn profile URL. Can be null. Array of person's phone numbers. Defaults to empty array. Array of person's email addresses (lowercase). Defaults to empty array. UUID of the associated company. Can be null. Person's seniority level (e.g., "Director", "VP"). Can be null. Array of department names. Defaults to empty array. Array of sub-department names. Defaults to empty array. Array of job functions. Defaults to empty array. Person's industry. Can be null. Array of skills. Defaults to empty array. Person's birth date in ISO 8601 format. Can be null. User ID of the lead owner. Can be null. Internal provider identifier. Can be null. Bullhorn CRM client contact ID. Can be null. 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. Soft delete timestamp. Can be null. Associated company object. Can be null. Returns all company fields via database join. Unique identifier (UUID) for the company ISO 8601 creation timestamp. Can be null. ISO 8601 last update timestamp. Can be null. Company name Detailed company description. Can be null. Brief summary of the company. Can be null. Employee count or range. Can be null. Company industry classification. Can be null. Array of company phone numbers. Company LinkedIn profile URL. Can be null. Company website URL. Can be null. Company domain name. Can be null. Headquarters city. Can be null. Headquarters postal/zip code. Can be null. Headquarters country. Can be null. URL to company logo image. Can be null. Legal company name. Can be null. Year the company was founded. Can be null. Revenue range. Can be null. Base Provider ID. Can be null. Bullhorn CRM client corporation ID. Can be null. Generic CRM identifier. Can be null. Detailed location information. Can be null. Bullhorn CRM client contact data. Can be null. Bullhorn client contact ID Bullhorn tasks association data Array of Bullhorn task objects with full task details Array of language objects with `language` and `level` properties. Array of education history objects. Array of work experience objects. Array of certificate objects. 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). Array of company objects (for company-type lists) Unique identifier (UUID) for the company ISO 8601 timestamp when the company was created. Can be null. ISO 8601 timestamp when the company was last updated. Can be null. Company name Detailed company description. Can be null. Brief summary of the company. Can be null. Employee count or range. Can be null. Company industry classification. Can be null. Array of company phone numbers. Defaults to empty array. Company LinkedIn profile URL. Can be null. Company website URL. Can be null. Company domain name. Can be null. Headquarters city. Can be null. Headquarters postal/zip code. Can be null. Headquarters country. Can be null. URL to company logo image. Can be null. Official legal name of the company. Can be null. Year the company was founded. Can be null. Company revenue or revenue range. Can be null. Internal provider identifier. Can be null. Bullhorn CRM client corporation ID. Can be null. Generic CRM identifier. Can be null. Detailed location information. Can be null. Headquarters location with `continent`, `country`, `state`, `city`, `street`, `postalCode`, `rawAddress`, and `coordinates` properties Array of additional office locations ## Response Examples ```json 200 - Person-Type List Success theme={null} [ { "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/..." } } ] ``` ```json 200 - Company-Type List Success theme={null} [ { "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": [] } } ] ``` ```json 200 - Empty List theme={null} [] ``` ```json 403 - Forbidden theme={null} { "error": { "code": "FORBIDDEN", "message": "User does not have access to this lead list" } } ``` ```json 404 - Not Found theme={null} { "error": { "code": "NOT_FOUND", "message": "Lead list with id 'invalid-uuid' not found" } } ``` ```json 401 - Unauthorized theme={null} { "error": { "code": "UNAUTHORIZED", "message": "Unauthorized" } } ``` ```json 500 - Server Error theme={null} { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } ``` ## How It Works 1. The endpoint authenticates the user via Clerk 2. Retrieves the lead list by the provided ID 3. Validates the user has access to the list (via `userIds` array or admin status) 4. 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 5. 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.