Lists: orchestrate enrichment

Lists are the centre of the Reverse Contact API. Every other endpoint is a single lookup: one person or one company in, one answer out, and your code chains the lookups, follows the async ones, retries, removes duplicates, counts credits and stores the results. A List orchestrates that whole pipeline for you, for up to 25,000 people or companies at a time. You hand it what you know about them: it identifies each one, buys the data you ask for under a budget you set, keeps the result, and tells you when it is done.

What a List orchestrates

For each line you send, a List runs the chain you would otherwise write yourself:

1. Identity. It picks the lookup each Signal needs. A Social profile URL is read from saved profiles, or live with live: true. An email, or a name with its company, is reversed to the person behind it. A domain, a company page URL or a company id leads to the company. A Signal no one matches is kept as Pending Intake, for free.
2. Deduplication. A person or a company already on the List is recognised and costs nothing, and lines naming the same identity with the same externalId are merged into one.
3. Data. It buys the data families you ask for (profile, company details, work email, phone number) only for the members that lack them. The lookup that adds a member already stores its profile, or its company details on a companies List, and the email of an email Signal becomes the member's work email, for free. Data a member already holds is never bought twice, and an email or a phone number already looked for is not looked for again.
4. Budget. It never spends more than the maxCredits you set. Before a step that would cross it, or when your balance runs out, it pauses, keeps the work done, and waits for you to resume.
5. Execution. The import runs in the background as one List Operation: free progress reads with long polling, a webhook each time it stops moving, a result for each line with your own externalId, and a cancel that never charges the lines not started.
6. Storage. Members and their data stay in the List, ready to read, to find by your own id, to export as CSV, or to grow with the next import.

One set of Lists for the app, your code and your agents

A List belongs to your workspace, not to the API. A List created with the API shows up in the app for your team. A List built in the app, from a Search or a file, can be read, filled and exported through the API. Ask, in the app, and your own agent, through the MCP server, and your code, through the API or the SDKs, work on the same Lists with the same rules. However a member entered, it is one member, charged once.

Single endpoints or a List

A single endpoint stays the right tool to look up one person or one company while a user waits: Enrich profile, Person profile or Find Email. Work on a set of people or companies you keep (a CRM segment, a prospect list that grows every week, target accounts to hand to your sales team) belongs in a List.

A List or Bulk enrichment

Bulk enrichment also takes up to 25,000 people in one request, without a List: it looks up each one, gives you a CSV with one row per item, and keeps nothing else. Choose by what you do with the result:

The job history lists both: your Bulk enrichment jobs and the jobs of your Lists, such as imports, with their progress and credits.

The building blocks of a List

The API flow, endpoint by endpoint

1. Create the List with Create a List: a name, and persons or companies.
2. Fill it with Signals. Add members takes up to 1,000 Signals and answers when they are done. Import members and data queues up to 25,000 Signals or a public CSV file, and can buy data families for each member.
3. Follow the import with Read a List operation, the pollUrl of the import, or be told by its webhookUrl.
4. Read the result with List members, or download it with Export a List.

Every call of this flow is free. You pay only for the members it adds and the data it buys (see What a List costs). Build your first List runs this flow step by step, with cURL, JavaScript, Python and the SDKs.

The API key needs the lists permission. A call that spends credits also needs the permission of what it buys, as the matching endpoint would: persons:enrich, companies:enrich or contact (see API key management).

Add members or run an import

An import of a CSV file sends its public URL in sourceUrl instead of signals: up to 25,000 rows and 25 MiB, with the columns matched from their headers (Social URL, email, first name, last name, company, domain).

Grow a List and buy data over time

A List is built for work that lasts: add a file today, buy emails for its members tomorrow, add the new leads of next week.

• Add new people at any time. Send them with Add members or an import: a person already on the List reads already_present and costs nothing.
• Buy data later. To buy data for members already on a List, import them again with families: their identity costs nothing, and only the data they lack is bought. An email or a phone number already looked for, found or not, is not looked for again.
• Take people out with Remove members, which also removes the data stored for them, and delete a List you no longer need with Delete a List.
• Imports run in turn. An import queued behind a paused one on the same List waits until you resume or cancel it (stopReason: "blocked_by_paused_operation"). Deleting a List returns 409 LIST_BUSY while an operation is queued, running or paused on it, while the lines of a cancelled one still wait for their result, or while a Search of the app is still adding people to it.

Link each member to your CRM with externalId

Send externalId on each Signal, the id of the line in your CRM or file. Each line result gives it back, the member keeps it, and List members finds a member by it (?externalId=crm-001). You never have to store our ids to find the member of a line. A member keeps the first externalId it received, and externalId is never used to find anyone.

Pending Intake

A Signal no one matches does not become a member: the List keeps it as a Pending Intake line, free, so you can see what was not found and fix it. Rows of Get a List and List members carry kind: "pending" for those lines and kind: "member" for members. Pending Intake is never enriched, and Export a List writes its lines with what was sent. Send a Signal again once it is fixed: when it finds someone, the new member replaces its Pending Intake line. Dismiss lines with the pendingIds of Remove members.

Control spend: maxCredits, pauses and resume

An import with families whose worst case is above 25 credits needs maxCredits, the most it may spend. The import pauses before a step that would cross it, keeps the work done, and reports stopReason: "max_credits" with the smallest ceiling that lets it continue in nextStep.minimumMaxCredits. A balance that runs out pauses it the same way, with stopReason: "balance". An import sent without maxCredits may spend up to its worst case.

To resume, send the same import again, same operationId, with a higher maxCredits or after adding credits: nothing already done is charged twice. To stop an import for good, cancel it with Cancel a List operation: the lines that had not started are never charged. See Pauses and how to resume.

What a List costs

Limits per workspace and per List

The Lists of a free trial that ends without a purchase are deleted 30 days after the trial ended.

The List calls count toward your per-minute and daily rate limits like any other call, with two exceptions: reading an operation is never counted, and the request that starts an import counts once on the daily limit and not on the per-minute one, whatever its number of lines. The lines of the import then take their share of your per-minute limit as they run, at most 80% of it, and wait when that share is taken. See Rate limits.

Error codes of the List endpoints

The List endpoints answer with the error envelope of every V2 endpoint (see Error handling & retries). Their own codes: