> Reverse Contact API documentation. This is the Markdown copy of https://docs.reversecontact.com/endpoints/lists
> Every page is listed at https://docs.reversecontact.com/llms.txt, every endpoint with its credit cost and status at https://docs.reversecontact.com/catalog.json

# All Lists

> Retrieve all Lists in your workspace with their ids, member counts and Pending Intake counts, then use a List id to read, fill or export it.

- Endpoint: `GET https://api.reversecontact.com/v2/lists`
- Credits: Free.
- Answer: synchronous.
- Available in: REST API, MCP tool `list_lists`, TypeScript and Python SDKs.
- Last verified: 2026-11-04

## Introduction

This endpoint returns all the Lists of your workspace, newest first, with how many members and how many [Pending Intake](https://docs.reversecontact.com/guides/lists#pending-intake) lines each one holds. Use it to find the `id` of a List before you read, fill or export it.

This endpoint is **free** (0 credits). It counts toward your per-minute rate limit like any other call. A workspace holds at most 200 Lists (1 on the free trial), so one page of the default size returns them all. A workspace that has never had a List gets an empty page.

The API key needs the `lists` permission (see [API key management](https://docs.reversecontact.com/guides/api-key-management)).

## Authorization

| Name     | Type   | Required | Description                                                                                         |
| -------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| `apikey` | string | Yes      | Your API key from the developer dashboard. Pass it via `Authorization: Bearer YOUR_API_KEY` header. |

## Query Parameters

| Name      | Type    | Required | Description                                                                                                   |
| --------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `perPage` | integer | No       | Lists per page, from 1 to 200. Defaults to 200.                                                               |
| `cursor`  | string  | No       | The `nextCursor` of the previous page. A malformed cursor, or one sent with other parameters, returns `400`.  |

## Response structure

| Field     | Type    | Description                                      |
| --------- | ------- | ------------------------------------------------ |
| `success` | boolean | `true` if the request was processed successfully |
| `error`   | `null`  | Always `null` on success                         |

**data** (ListPage): One page of Lists

| Field        | Type           | Description                                               |
| ------------ | -------------- | --------------------------------------------------------- |
| `nextCursor` | string \| null | Send it back as `cursor` for the next page, `null` on the last page |

**items** (List[]): The Lists of this page, newest first

| Field                | Type           | Description                                                                 |
| -------------------- | -------------- | --------------------------------------------------------------------------- |
| `id`                 | string         | List id (UUID)                                                              |
| `name`               | string         | List name                                                                   |
| `entity`             | string         | `persons` or `companies`: a List never mixes both                           |
| `memberCount`        | number         | List Members                                                                |
| `pendingIntakeCount` | number         | Lines no one matched, kept as Pending Intake                                |
| `revision`           | number         | Raised by every change to the members                                       |
| `archivedAt`         | string \| null | Archive date (ISO 8601), `null` for an active List                          |
| `createdAt`          | string         | Creation date (ISO 8601)                                                    |
| `updatedAt`          | string         | Last update date (ISO 8601)                                                 |
| `originQuery`        | object \| null | The Search filters the List was built from in the app, `null` otherwise     |
| `originLastFind`     | object \| null | The last run of those filters, `null` otherwise                             |

`quotas` and `metadata` are the blocks of every V2 response: see [Usage](https://docs.reversecontact.com/endpoints/usage#response-structure).

## Code examples

**Code Examples**

```bash [cURL]
curl https://api.reversecontact.com/v2/lists \
  -H "Authorization: Bearer YOUR_API_KEY"
```
```javascript [JavaScript]
const response = await fetch("https://api.reversecontact.com/v2/lists", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});

const payload = await response.json();
for (const list of payload.data.items) {
  console.log(list.id, list.name, `${list.memberCount} members`);
}
```
```python [Python]
import requests

response = requests.get(
    "https://api.reversecontact.com/v2/lists",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

for item in response.json()["data"]["items"]:
    print(item["id"], item["name"], f"{item['memberCount']} members")
```

## Example response

**Example Response**

```json [200 - Success]
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40",
        "name": "Q4 sales leaders",
        "entity": "persons",
        "memberCount": 1240,
        "pendingIntakeCount": 18,
        "revision": 7,
        "archivedAt": null,
        "createdAt": "2026-10-20T09:12:44.000Z",
        "updatedAt": "2026-10-27T16:03:10.000Z",
        "originQuery": null,
        "originLastFind": null
      }
    ],
    "nextCursor": null
  },
  "error": null,
  "quotas": {
    "creditsConsumed": 0,
    "workspace": {
      "id": "ws_abc123",
      "credits": { "total": 10000, "used": 4521, "left": 5479 }
    }
  },
  "metadata": {
    "requestId": "014e621a-ecb1-4849-8afe-3f4f7cd7514d",
    "executionTimeMs": 38
  }
}
```