Endpoints // Lists

All Lists

New

Last verified November 4, 2026

Available inAPI MCP SDK

Read the Lists of your workspace with their member and Pending Intake counts, for free.

GET/v2/lists

Credits

Free.

Introduction

This endpoint returns all the Lists of your workspace, newest first, with how many members and how many 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).

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

dataobject

One page of Lists

Show child attributes

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

itemsobject[]

The Lists of this page, newest first

Show child attributes

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.

Code examples

Code Examples

curl https://api.reversecontact.com/v2/lists \
  -H "Authorization: Bearer YOUR_API_KEY"

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`);
}

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

200 - Success

Example Response

{
  "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": "req_l1i2s3t4s5a6",
    "executionTimeMs": 38
  }
}