> ## Documentation Index
> Fetch the complete documentation index at: https://guide.rolodexcrm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch Lists

## `GET` lists

Fetch multiple lists.

`GET` `/user-api/v1/lists`

### Headers

| Header              | Value               |
| ------------------- | ------------------- |
| `x-rolodex-api-key` | `f1e2d3c4b5a697...` |

### Query Parameters

<ParamField path="limit" type="string">
  Number of records to return (Default:25)
</ParamField>

<ParamField path="offset" type="string">
  Number of records to skip (Default:0)
</ParamField>

<ParamField path="order by" type="string">
  Sort order: `created_at:asc`, `created_at:desc`, `name:asc`, `name:desc`
</ParamField>

<ParamField path="include" type="string">
  Related data to include: `contacts`, `companies`
</ParamField>

<ParamField path="type" type="string">
  Filter by list type: `CONTACT`, `COMPANY`
</ParamField>

### Response

```json theme={null}
{
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 50
  },
  "data": [
    {
      "id": "list_12345",
      "name": "Q1 Prospects",
      "description": "High-priority prospects for Q1 outreach",
      "type": "CONTACT",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    },
    {
      "id": "list_67890",
      "name": "Enterprise Clients",
      "description": "Large enterprise companies we're targeting",
      "type": "COMPANY",
      "created_at": "2025-01-14T09:15:00Z",
      "updated_at": "2025-01-14T09:15:00Z"
    }
  ]
}
```

### With `Include` Paramters

`GET` `/user-api/v1/lists?include=contacts,companies&type=CONTACT`

### Response with all includes (CONTACT list)

```json theme={null}
{
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 50
  },
  "data": [
    {
      "id": "list_12345",
      "name": "Q1 Prospects",
      "description": "High-priority prospects for Q1 outreach",
      "type": "CONTACT",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z",
      "contacts": [
        {
          "id": "contact_123",
          "full_name": "John Doe",
          "image_url": "https://example.com/avatar.jpg"
        }
      ]
    }
  ]
}
```

### Response with all includes (COMPANY list)

```json theme={null}
{
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 50
  },
  "data": [
    {
      "id": "list_67890",
      "name": "Enterprise Clients",
      "description": "Large enterprise companies we're targeting",
      "type": "COMPANY",
      "created_at": "2025-01-14T09:15:00Z",
      "updated_at": "2025-01-14T09:15:00Z",
      "companies": [
        {
          "id": "company_456",
          "name": "Acme Corp",
          "logo_url": "https://example.com/logo.png"
        }
      ]
    }
  ]
}
```

## `GET` a List

Fetch one list.

`GET` `/user-api/v1/lists/:id`

### Path Parameters

<ParamField path="id" type="string">
  List ID
</ParamField>

### Query Parameters

<ParamField path="include" type="string">
  Related data to include: `contacts`, `companies`
</ParamField>

### Endpoint Example

`GET` `/user-api/v1/lists/list_12345?include=contacts`

### Response

```json theme={null}
{
  "data": {
    "id": "list_12345",
    "name": "Q1 Prospects",
    "description": "High-priority prospects for Q1 outreach",
    "type": "CONTACT",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}
```