Endpoints // Lists

Get a List

New

Last verified November 4, 2026

Available inAPI MCP SDK

Read a List and the first page of its rows, members and Pending Intake, for free.

GET/v2/lists/:listId

Credits

Free.

Introduction

The Get a List endpoint returns one List and one page of its rows, ordered by the date they were added: the List Members (kind: "member") and the lines no one matched, kept as Pending Intake (kind: "pending"). It reads what the List already holds and never looks anyone up.

This endpoint is free (0 credits). It counts toward your per-minute rate limit like any other call. To page through the rows without the List header, or to find members by your own identifier, use List members.

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.

Request

The route is GET /v2/lists/:listId.

Path parameters

Name	Type	Required	Description
`listId`	string	Yes	List id (UUID)

Query Parameters

Name	Type	Required	Description
`kind`	string	No	`all` (default) mixes members and Pending Intake by added date, `members` or `pending` returns one kind only
`perPage`	integer	No	Rows per page, from 1 to 1,000. Defaults to 100.
`cursor`	string	No	The `nextCursor` of the previous page, sent with the same `kind`. 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

The List and one page of its rows

Show child attributes

Field	Type	Description
`list`	object	The List, with the fields of All Lists
`members`	array	One page of rows: members (`kind: "member"`) and Pending Intake (`kind: "pending"`). Each row is described in List members.
`nextCursor`	string \| null	Send it back as `cursor` for the next page, `null` on the last page

quotas and metadata are the blocks of every V2 response: see Usage.

A List that does not exist in your workspace returns 404 LIST_NOT_FOUND, or 404 LISTS_NOT_ACTIVATED when the workspace has never had a List.

Code examples

Code Examples

curl "https://api.reversecontact.com/v2/lists/3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40?perPage=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

const listId = "3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40";
const response = await fetch(
  `https://api.reversecontact.com/v2/lists/${listId}?perPage=50`,
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);

const { data } = await response.json();
console.log(data.list.name, `${data.list.memberCount} members`);
console.log("Rows on this page:", data.members.length);

import requests

list_id = "3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40"
response = requests.get(
    f"https://api.reversecontact.com/v2/lists/{list_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"perPage": 50}
)

data = response.json()["data"]
print(data["list"]["name"], f"{data['list']['memberCount']} members")

Example response

200 - Success

Example Response

{
  "success": true,
  "data": {
    "list": {
      "id": "3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40",
      "name": "Q4 sales leaders",
      "entity": "persons",
      "memberCount": 2,
      "pendingIntakeCount": 1,
      "revision": 3,
      "archivedAt": null,
      "createdAt": "2026-10-28T09:12:44.000Z",
      "updatedAt": "2026-10-28T09:20:02.000Z",
      "originQuery": null,
      "originLastFind": null
    },
    "members": [
      {
        "kind": "member",
        "id": "9b1e4c7a-2d3f-4e8a-b6c5-0a1f2e3d4c5b",
        "entityId": "prs_01jbd5vewyenebxgaz869ffe5t",
        "linkedinUrl": "https://www.social.com/in/janedoe",
        "status": "enriched",
        "fields": {
          "name": "Jane Doe",
          "headline": "VP Sales at Acme Corp",
          "company": "Acme Corp",
          "location": { "country": "France" },
          "url": "https://www.social.com/in/janedoe",
          "status": "enriched"
        },
        "addedAt": "2026-10-28T09:15:31.000Z",
        "families": {
          "profile": { "enrichedAt": "2026-10-28T09:15:31.000Z" }
        },
        "externalId": "crm-001"
      },
      {
        "kind": "pending",
        "id": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
        "signal": { "email": "unknown.person@example.com" },
        "source": "paste",
        "addedAt": "2026-10-28T09:15:32.000Z",
        "fields": {}
      }
    ],
    "nextCursor": null
  },
  "error": null,
  "quotas": {
    "creditsConsumed": 0,
    "workspace": {
      "id": "ws_abc123",
      "credits": { "total": 10000, "used": 4521, "left": 5479 }
    }
  },
  "metadata": {
    "requestId": "req_g1e2t3l4i5s6",
    "executionTimeMs": 44
  }
}