Add members

Introduction

The Add members endpoint turns up to 1,000 Signals into List Members and answers once they are all done. A Signal is what you know about someone: a Social profile URL, an email, or a first and last name with a company for a person; a company page URL, a domain or a company id for a company. The response holds one result per Signal, in the order you sent them, so you can match each line of your file to the member it became.

A Signal no one matches is kept on the List as Pending Intake, free. When a Signal sent again finds someone, the new member replaces its Pending Intake line. A person or company already on the List is left as it is, free, with one exception: the email of an email Signal becomes the member's work email (families.contactEmail, source: "signal:paste" or "signal:file") when the List has not found one yet, for free. This holds for a new member too, so a later email lookup never buys back an address you gave.

To add more than 1,000 Signals, to buy data families (profile, company, email, phone) for each member, to set a credit ceiling or to be told by webhook, use Import members and data instead.

Credits

The call itself is free: only the new members are charged, at the price of the Signal that found them.

A Signal of the other kind (a company on a people List, a person on a companies List) refuses the request with 400 LIST_ENTITY_MISMATCH. Before anything is added, the API checks that your balance covers what the batch could charge: every Signal at its price, except a Social URL already on the List or repeated in the batch (an email, a name, a domain or a company id is always counted, and a company page URL or id at 1 credit). Below that, the request returns 402 and nothing is charged. Each new member is then charged before it is written. A person or company that asked us to stop processing their data is refused (data_subject_blocked): nothing is kept or charged for it. data.creditsConsumed and quotas.creditsConsumed both give what the call charged.

The API key needs the lists permission, plus persons:enrich for a people List or companies:enrich for a companies List (see API key management).

Authorization

Request body

The List is named in the path: POST /v2/lists/:listId/members.

Each Signal is an object with the fields that identify one person or one company:

One invalid Signal refuses the whole request before anything is charged, and error.details.signalIndex gives its position.

Response structure

The request answers once every Signal has been handled. It runs within a 62-second time limit: past it, it returns 504, and the members already added stay added and charged. Read the List to see where it stopped, or send large batches through the import.

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

Errors

With several Signals, a full List does not refuse the request: it answers 200, the line that met the limit reads refused (member_limit or pending_intake_limit), the next ones read not_reached, and stoppedReason is member_cap or pending_cap.

Code examples

curl -X POST https://api.reversecontact.com/v2/lists/3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40/members \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signals": [
      { "linkedinUrl": "https://www.social.com/in/janedoe", "externalId": "crm-001" },
      { "email": "john.smith@acme.com", "externalId": "crm-002" },
      { "firstName": "Ana", "lastName": "Lopez", "companyDomain": "northwind.com", "externalId": "crm-003" }
    ]
  }'

const listId = "3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40";
const response = await fetch(`https://api.reversecontact.com/v2/lists/${listId}/members`, {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    signals: [
      { linkedinUrl: "https://www.social.com/in/janedoe", externalId: "crm-001" },
      { email: "john.smith@acme.com", externalId: "crm-002" },
      { firstName: "Ana", lastName: "Lopez", companyDomain: "northwind.com", externalId: "crm-003" }
    ]
  })
});

const { data } = await response.json();
for (const result of data.results) {
  console.log(result.externalId, result.outcome, result.memberId ?? result.pendingId);
}
console.log("Credits charged:", data.creditsConsumed);

import requests

list_id = "3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40"
response = requests.post(
    f"https://api.reversecontact.com/v2/lists/{list_id}/members",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "signals": [
            {"linkedinUrl": "https://www.social.com/in/janedoe", "externalId": "crm-001"},
            {"email": "john.smith@acme.com", "externalId": "crm-002"},
            {"firstName": "Ana", "lastName": "Lopez", "companyDomain": "northwind.com", "externalId": "crm-003"}
        ]
    }
)

data = response.json()["data"]
for result in data["results"]:
    print(result.get("externalId"), result["outcome"])
print("Credits charged:", data["creditsConsumed"])

Example response

In this example, the Social profile URL adds a new member (1 credit), the email names a person already on the List (free), and no one matches the name (free, kept as Pending Intake).

{
  "success": true,
  "data": {
    "inserted": 1,
    "skipped": 1,
    "refused": 0,
    "unresolvedCount": 1,
    "creditsConsumed": 1,
    "results": [
      {
        "index": 0,
        "outcome": "added",
        "externalId": "crm-001",
        "memberId": "9b1e4c7a-2d3f-4e8a-b6c5-0a1f2e3d4c5b",
        "entityId": "prs_01jbd5vewyenebxgaz869ffe5t"
      },
      {
        "index": 1,
        "outcome": "already_present",
        "externalId": "crm-002",
        "memberId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "entityId": "prs_01h2x3y4z5a6b7c8d9e0f1g2h3"
      },
      {
        "index": 2,
        "outcome": "not_found",
        "externalId": "crm-003",
        "pendingId": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b"
      }
    ]
  },
  "error": null,
  "quotas": {
    "creditsConsumed": 1,
    "workspace": {
      "id": "ws_abc123",
      "credits": { "total": 10000, "used": 4522, "left": 5478 }
    }
  },
  "metadata": {
    "requestId": "req_a1d2d3m4e5m6",
    "executionTimeMs": 2140
  }
}