Import members and data

Introduction

The Import members and data endpoint queues up to 25,000 Signals, or a public CSV file or Google Sheet, as one operation on a List. It answers at once with an operationId and a pollUrl, then works in the background: each line is identified like an add, and with families, the data you ask for is bought for each member, new or already on the List.

Use it instead of Add members for more than 1,000 Signals, to fill a List with emails, phone numbers, profiles or company details, to set a credit ceiling, or to be told by webhook when the import stops moving. Follow it with Read a List operation and stop it with Cancel a List operation.

Credits

Queuing the import is free: the operation is charged line by line as it runs, and never more than maxCredits.

Data a member already holds is never bought again, and an email or a phone number already looked for, found or not, is not looked for again: an import replayed on the same List charges only what is missing. A line no one matches is kept as Pending Intake, free. When a Signal sent again finds someone, the new member replaces its Pending Intake line.

The contact_phone family needs phone finding on your workspace, as Find Phone does. Without it, the member of each line that asks for a phone number is still added, the line reads resolved with errorCode: "CONTACT_PHONE_FINDER_DISABLED", and no phone number is charged.

The API key needs the lists permission, plus the permission of each thing the import buys: persons:enrich for people and their profiles, companies:enrich for companies and company details, contact for the email and phone families (see API key management).

The request that starts an import counts as one request on your daily limit and is not counted against your per-minute limit, whatever its number of lines. Its lines then take their share of your per-minute limit as they run, at most 80% of it, and wait when that share is taken. Reading the operation is never counted. See Rate limits.

Authorization

Request body

The List is named in the path: POST /v2/lists/:listId/intake/signals. Send signals or sourceUrl, not both.

The credit ceiling

When families makes the worst case of the import (every line a new member, every family bought, every email and phone found) higher than 25 credits, the request must carry maxCredits: without it, it returns 400 LIST_INVALID_INPUT and nothing is queued. maxCredits is your consent to spend up to that amount, and the operation stops before a step that would cross it. An import without families needs no ceiling: it costs at most the identity of its lines. An import sent without maxCredits gets its worst case as ceiling, so it may spend up to that amount.

Deduplication and replays

Lines naming the same identity with the same externalId are deduplicated: duplicateCount gives how many were dropped. Two lines naming the same person under two externalId values stay two lines, and the second one reads already_present.

With operationId, sending the same request again returns the operation it created, whatever its state, and charges nothing twice. The same operationId with other Signals, families, live or source returns 400 LIST_INVALID_INPUT. A cancelled operation stays cancelled: a new run needs a new operationId.

Pauses and how to resume

The operation pauses instead of failing when it cannot go on, and keeps the work done:

• maxCredits reached (stopReason: "max_credits"): send the same request again, same operationId, with a higher maxCredits. nextStep.minimumMaxCredits gives the smallest ceiling that lets it continue.
• Balance too low (stopReason: "balance"): add credits, then send the same request again with the same operationId.
• Paused from the app (stopReason: "paused_by_user"): send the same request again with the same operationId.

A paused operation holds the imports queued after it on the same List (stopReason: "blocked_by_paused_operation", with nextStep.blockingOperationId): resume or cancel it to let them start. An operation also stops for good when the List reaches its member or Pending Intake limit (list_member_limit, list_pending_intake_limit); the lines it did not reach are not charged.

Lines that name no one, or the wrong kind

A line never refuses the whole import. A line naming a company on a people List, or a person on a companies List, reads refused with errorCode: "ENTITY_MISMATCH". A Signal that identifies no one reads failed with errorCode: "LIST_INVALID_INPUT", and a row of a sourceUrl file with no usable column reads refused with errorCode: "NO_INPUT". These lines are free, and Read a List operation gives them line by line.

Response structure

The request answers 202 at once, with a Retry-After: 5 header. It runs within a 15-second time limit, which a slow sourceUrl download can cross: past it, it returns 504, and the import may have been queued all the same. Always send an operationId for this reason: the same request sent again with it returns the operation if it exists, or queues it, and never charges twice.

quotas and metadata are the blocks of every V2 response: see Usage. quotas.creditsConsumed is 0: the credits of the operation appear in its creditsConsumed as it runs.

Then read the operation at its pollUrl until clientAction is done: see Read a List operation.

Webhook callback

With webhookUrl, that URL receives one POST each time the operation stops moving: it completed, paused at a ceiling or a low balance, was cancelled, or its outcome became unknown. It receives nothing while the operation runs. The event says which operation changed and carries no member data: read the operation, and its per-line results, at pollUrl with your API key.

This event is not the lookup callback of the Webhooks guide: it has its own payload, below, and is sent to webhookUrl only, never to the workspace webhook URL of Settings > Webhooks.

The request is JSON and its x-reversecontact-event header names the event, list.operation.updated. Answer with a 2xx within 10 seconds. A timeout, a 408, a 429 or a 5xx is tried again twice, after 2 then 5 seconds; a redirect is never followed. Each state is sent once, so a receiver that missed it can always read the operation at pollUrl.

The URL must be public HTTPS: a private, local or unresolvable host returns 400 WEBHOOK_URL_UNREACHABLE and nothing is queued. It is checked again before each delivery.

Errors

Code examples

curl -X POST https://api.reversecontact.com/v2/lists/3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40/intake/signals \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operationId": "c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
    "signals": [
      { "linkedinUrl": "https://www.social.com/in/janedoe", "externalId": "crm-001" },
      { "email": "john.smith@acme.com", "externalId": "crm-002" }
    ],
    "families": ["contact_email"],
    "maxCredits": 100,
    "webhookUrl": "https://example.com/hooks/reversecontact"
  }'

const KEY = "YOUR_API_KEY";
const BASE = "https://api.reversecontact.com";
const listId = "3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40";

// Queue the import, then follow it until it no longer moves.
const queued = await fetch(`${BASE}/v2/lists/${listId}/intake/signals`, {
  method: "POST",
  headers: { "Authorization": `Bearer ${KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    operationId: crypto.randomUUID(),
    signals: [
      { linkedinUrl: "https://www.social.com/in/janedoe", externalId: "crm-001" },
      { email: "john.smith@acme.com", externalId: "crm-002" }
    ],
    families: ["contact_email"],
    maxCredits: 100
  })
});
const { data: ack } = await queued.json();

let operation;
do {
  const response = await fetch(`${BASE}${ack.pollUrl}?wait=20`, {
    headers: { "Authorization": `Bearer ${KEY}` }
  });
  operation = (await response.json()).data;
} while (operation.clientAction === "poll");

console.log(operation.status, `${operation.creditsConsumed} credits`, operation.nextStep?.message ?? "");

import uuid
import requests

KEY = "YOUR_API_KEY"
BASE = "https://api.reversecontact.com"
list_id = "3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40"
headers = {"Authorization": f"Bearer {KEY}"}

ack = requests.post(
    f"{BASE}/v2/lists/{list_id}/intake/signals",
    headers=headers,
    json={
        "operationId": str(uuid.uuid4()),
        "signals": [
            {"linkedinUrl": "https://www.social.com/in/janedoe", "externalId": "crm-001"},
            {"email": "john.smith@acme.com", "externalId": "crm-002"}
        ],
        "families": ["contact_email"],
        "maxCredits": 100
    }
).json()["data"]

while True:
    operation = requests.get(f"{BASE}{ack['pollUrl']}", headers=headers, params={"wait": 20}, timeout=30).json()["data"]
    if operation["clientAction"] != "poll":
        break

print(operation["status"], operation["creditsConsumed"], "credits")

Example response

{
  "success": true,
  "data": {
    "operationId": "c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
    "pollUrl": "/v2/lists/3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40/operations/c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f/progress",
    "totalRows": 2,
    "duplicateCount": 0
  },
  "error": null,
  "quotas": {
    "creditsConsumed": 0,
    "workspace": {
      "id": "ws_abc123",
      "credits": { "total": 10000, "used": 4522, "left": 5478 }
    }
  },
  "metadata": {
    "requestId": "req_i1n2t3a4k5e6",
    "executionTimeMs": 88
  }
}

{
  "event": "list.operation.updated",
  "operationId": "c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
  "listId": "3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40",
  "status": "completed",
  "clientAction": "done",
  "stopReason": null,
  "pollUrl": "/v2/lists/3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40/operations/c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f/progress",
  "occurredAt": "2026-10-28T09:21:40.000Z"
}