Endpoints // Lists

Create a List

New

Last verified November 4, 2026

Available inAPI MCP SDK

Create a people or companies List, with an Idempotency-Key to retry safely.

POST/v2/lists

Credits

Free.

Introduction

The Create a List endpoint creates an empty List of people or of companies. A List never mixes both: its entity decides which Signals it accepts and which data families it can hold. Fill it afterwards with Add members or Import members and data.

Creating a List is free (0 credits). A workspace holds at most 200 Lists, and 1 on the free trial: past that, the request returns 409 LIST_LIMIT_REACHED. When the name is already taken, the List is created as Name (2).

The first List of a workspace also sets up where its Lists are stored. While that runs, the request returns 503 LISTS_PREPARING, with error.details.retryAfterSeconds: send the same request again a few seconds later, with the same Idempotency-Key.

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 body

Name	Type	Required	Description
`name`	string	Yes	List name, 1 to 200 characters. Spaces around it are removed.
`entity`	string	Yes	`persons` for people, `companies` for companies

Retry safely with Idempotency-Key

Send an Idempotency-Key header (1 to 200 printable ASCII characters, no spaces) to make the creation safe to retry: a second request with the same key returns the List the first one created, with 201, instead of creating Name (2). Reusing the key for the other entity returns 409 IDEMPOTENCY_KEY_REUSED.

Response structure

The response has status 201.

Field	Type	Description
`success`	boolean	`true` if the List was created
`error`	`null`	Always `null` on success

dataobject

The List created, or the List this Idempotency-Key created

Show child attributes

Field	Type	Description
`id`	string	List id (UUID): keep it to fill and read the List
`name`	string	List name, suffixed when the name was already taken
`entity`	string	`persons` or `companies`
`memberCount`	number	List Members, `0` for a new List
`pendingIntakeCount`	number	Pending Intake lines, `0` for a new List
`revision`	number	Raised by every change to the members
`archivedAt`	`null`	`null` for an active List
`createdAt`	string	Creation date (ISO 8601)
`updatedAt`	string	Last update date (ISO 8601)
`originQuery`	`null`	`null` for a List created through the API
`originLastFind`	`null`	`null` for a List created through the API

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

Errors

Status	Code	Meaning
`400`	`LIST_INVALID_INPUT`	The `Idempotency-Key` header is malformed, or `name` holds only spaces
`409`	`LIST_LIMIT_REACHED`	The workspace already has 200 Lists (1 on the free trial)
`409`	`IDEMPOTENCY_KEY_REUSED`	The key already created a List of the other `entity`
`422`	`VALIDATION_ERROR`	`name` is missing or too long, or `entity` is not a known value
`503`	`LISTS_PREPARING`	The first List of the workspace is being set up: retry in a few seconds

Code examples

Code Examples

curl -X POST https://api.reversecontact.com/v2/lists \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-sync-2026-10-28" \
  -d '{ "name": "Q4 sales leaders", "entity": "persons" }'

const response = await fetch("https://api.reversecontact.com/v2/lists", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Idempotency-Key": "crm-sync-2026-10-28"
  },
  body: JSON.stringify({ name: "Q4 sales leaders", entity: "persons" })
});

const { data: list } = await response.json();
console.log("List created:", list.id);

import requests

response = requests.post(
    "https://api.reversecontact.com/v2/lists",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
        "Idempotency-Key": "crm-sync-2026-10-28"
    },
    json={"name": "Q4 sales leaders", "entity": "persons"}
)

print("List created:", response.json()["data"]["id"])

Example response

Example Response

{
  "success": true,
  "data": {
    "id": "3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40",
    "name": "Q4 sales leaders",
    "entity": "persons",
    "memberCount": 0,
    "pendingIntakeCount": 0,
    "revision": 1,
    "archivedAt": null,
    "createdAt": "2026-10-28T09:12:44.000Z",
    "updatedAt": "2026-10-28T09:12:44.000Z",
    "originQuery": null,
    "originLastFind": null
  },
  "error": null,
  "quotas": {
    "creditsConsumed": 0,
    "workspace": {
      "id": "ws_abc123",
      "credits": { "total": 10000, "used": 4521, "left": 5479 }
    }
  },
  "metadata": {
    "requestId": "req_c1r2e3a4t5e6",
    "executionTimeMs": 52
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "LIST_LIMIT_REACHED",
    "message": "This workspace already has 200 lists"
  },
  "quotas": {
    "creditsConsumed": 0,
    "workspace": {
      "id": "ws_abc123",
      "credits": { "total": 10000, "used": 4521, "left": 5479 }
    }
  },
  "metadata": {
    "requestId": "req_c1r2e3a4t5e7",
    "executionTimeMs": 21
  }
}