> ## 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 Lead List

> Retrieves a single lead list by ID with populated persons or companies

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.

<Note>
  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.
</Note>

## Request

<ParamField path="id" type="string (UUID)" required>
  The unique identifier of the lead list to retrieve.
</ParamField>

## Response

Returns the lead list with populated items (persons or companies depending on list type).

### Base Fields

<ResponseField name="id" type="string (UUID)" required>
  Unique identifier for the lead list.
</ResponseField>

<ResponseField name="icpId" type="string (UUID) | null" required>
  The ID of the associated Ideal Customer Profile, or `null` if not linked.
</ResponseField>

<ResponseField name="name" type="string" required>
  The display name of the lead list.
</ResponseField>

<ResponseField name="type" type="string" required>
  The type of leads in this list. Either `"person"` or `"company"`.
</ResponseField>

<ResponseField name="startDate" type="string" required>
  ISO 8601 timestamp for the campaign start date.
</ResponseField>

<ResponseField name="endDate" type="string" required>
  ISO 8601 timestamp for the campaign end date.
</ResponseField>

<ResponseField name="personIds" type="array" required>
  Array of person/lead IDs stored in the list.
</ResponseField>

<ResponseField name="companyIds" type="array" required>
  Array of company UUIDs stored in the list.
</ResponseField>

<ResponseField name="userIds" type="array" required>
  Array of user IDs with access to this lead list.
</ResponseField>

<ResponseField name="createdAt" type="string" required>
  ISO 8601 timestamp of when the lead list was created.
</ResponseField>

<ResponseField name="updatedAt" type="string" required>
  ISO 8601 timestamp of when the lead list was last updated.
</ResponseField>

### Populated Fields

<ResponseField name="persons" type="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)
</ResponseField>

<ResponseField name="companies" type="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
</ResponseField>

## Response Examples

<ResponseExample>
  ```json 200 Person-Type List theme={null}
  {
    "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": []
        }
      }
    ]
  }
  ```

  ```json 200 Company-Type List theme={null}
  {
    "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"
      }
    ]
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "message": "LeadList with id 'invalid-id' not found"
    }
  }
  ```
</ResponseExample>

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