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

# List Lead Lists

> Retrieves all lead lists accessible to the authenticated user

Retrieves a list of all lead lists that the currently authenticated user has access to. Lead lists are collections of leads (persons or companies) organized for sales prospecting campaigns.

## Authentication

This endpoint requires authentication. The user must be signed in to access lead lists.

<Note>
  Users can only see lead lists they have been granted access to via the
  `userIds` field. Admin users can see all lead lists in the organization.
</Note>

## Request

This endpoint does not require any query parameters or request body.

## Response

Returns an array of lead list objects.

<ResponseField name="leadlists" type="array">
  An array of lead list objects accessible to the user.

  <Expandable title="Lead list object properties">
    <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 Ideal Customer Profile (ICP) associated with this lead list. May be `null` if not linked to an ICP.
    </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"` for individual contacts or `"company"` for company leads.
    </ResponseField>

    <ResponseField name="startDate" type="string" required>
      ISO 8601 timestamp indicating the start date of the lead list campaign.
    </ResponseField>

    <ResponseField name="endDate" type="string" required>
      ISO 8601 timestamp indicating the end date of the lead list campaign.
    </ResponseField>

    <ResponseField name="personIds" type="array" required>
      Array of person/lead IDs included in this list (when `type` is `"person"`).
    </ResponseField>

    <ResponseField name="companyIds" type="array" required>
      Array of company IDs included in this list (when `type` is `"company"`).
    </ResponseField>

    <ResponseField name="userIds" type="array" required>
      Array of Clerk user IDs that have 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>
  </Expandable>
</ResponseField>

## Response Examples

<ResponseExample>
  ```json 200 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", "lead_ghi789"],
      "companyIds": [],
      "userIds": ["user_xyz789", "user_abc123"],
      "createdAt": "2024-01-02T10:30:00.000Z",
      "updatedAt": "2024-01-15T14:22:00.000Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "icpId": null,
      "name": "Enterprise Accounts",
      "type": "company",
      "startDate": "2024-02-01T00:00:00.000Z",
      "endDate": "2024-06-30T23:59:59.000Z",
      "personIds": [],
      "companyIds": ["770e8400-e29b-41d4-a716-446655440001", "770e8400-e29b-41d4-a716-446655440002"],
      "userIds": ["user_xyz789"],
      "createdAt": "2024-02-01T09:00:00.000Z",
      "updatedAt": "2024-02-10T11:45:00.000Z"
    }
  ]
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Unauthorized"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Status Code | Error Code       | Description                                               |
| ----------- | ---------------- | --------------------------------------------------------- |
| 401         | `UNAUTHORIZED`   | User is not authenticated. Ensure a valid session exists. |
| 500         | `INTERNAL_ERROR` | An unexpected server error occurred.                      |