Skip to main content
POST
Enrich

Credits and plans

PAYG is Pay-as-you-go. AYCE is All-you-can-eat. PAYG prices add together. Only populated details selected by reveal add email or mobile charges. Unmatched inputs cost 0 credits. There is no SmartSearch fee on this endpoint because it takes identifiers rather than a search filter.

When to use Enrich

Use Enrich when you know which contacts you want. Send RBID_PAO values as personIds to retrieve people selected from a free View sample, or send existing email addresses as emails to look up their contact and company fields. This endpoint looks up records in the RevenueBase dataset. It does not verify whether an email is deliverable or perform a fresh employment check. Each returned row represents a person at a company.

Example: retrieve contacts selected from View

Set your API key as REVENUEBASE_API_KEY. In your application, use real RBID_PAO values returned by View. The sample below contains the two real IDs returned by View, and selects email without mobile.
On PAYG, this request consumes credits. Omitting reveal, or sending null, selects both email and mobile. Set columns as well: fewer returned fields do not remove charges for selected details.
Response captured from the local test API on October 13, 2026 using an AYCE account. Results can change as the dataset or account changes.
Both submitted IDs matched. The response uses those IDs as keys. On PAYG, the two returned matches and their two populated selected emails would cost 4 credits; the AYCE capture used 0 credits.

Send a list in one request

You can send emails, personIds, or both. The combined limit is 10,000 identifiers after normalization and duplicate removal. For example, 6,000 emails and 4,000 person IDs fit in one request. Send the lists as JSON arrays; this endpoint does not upload a file. For each identifier, Enrich returns at most one matching contact row. If an identifier matches multiple rows, the endpoint selects one. It does not return every company or employment record for that person. Sending the same contact’s email and person ID can produce two match entries, one under each key. PAYG charges each returned entry. Use one identifier per contact when you want to avoid retrieving it twice.

Control the credit hold and returned fields

A PAYG hold assumes every submitted array entry will match a row with every selected detail. The hold counts entries before normalization and duplicate removal. Remove duplicates before sending to keep that amount down. For the two submitted IDs with reveal: ["email"], PAYG would reserve 4 credits. Both matches have an email, so the final PAYG charge would also be 4 credits. AYCE used 0 credits for this capture. A 402 INSUFFICIENT_CREDITS response rejects the request before lookup, even when you expect many identifiers to be unmatched. Split the list or select fewer details to lower the hold. Choose fields from Get Columns. Unknown requested columns are ignored on this endpoint. Available company fields on a contact row add no separate company-row charge. On PAYG, requested email or mobile fields not selected by reveal become hasEmail or hasMobile availability booleans. On AYCE, columns controls the returned fields; reveal does not mask them. Read X-Credits-Charged and X-Credits-Remaining on a metered response for the settled charge and remaining balance.

Errors and retries

An unsuccessful request releases its hold. A valid list with no matches returns matches: {} and matched: 0 for 0 credits. Repeating a paid request can charge again, including for the same identifiers. After an ambiguous timeout, the earlier call may already have completed; do not assume a retry will avoid another charge.

Next step

Join the returned matches to your input identifiers in your application. To retrieve a broader audience rather than a known list, begin with Count and View. For a downloadable file, use Estimate and Export.

Authorizations

X-Key
string
header
required

Body

application/json

Contact lookup by emails, personIds (RBID_PAO), or both. Up to 10,000 normalized distinct identifiers combined. Specify columns and reveal explicitly to control returned fields and PAYG credit costs.

emails
string[]

Existing email addresses to match to contact records. May be combined with personIds within the shared 10,000-identifier cap after normalization and deduplication. An email used as a lookup key does not waive the email-reveal charge on PAYG.

personIds
string[]

RBID_PAO person-at-company identifiers, such as those returned by View. May be combined with emails within the shared 10,000-identifier cap. Sending both identifiers for the same contact can return two billable match entries on PAYG.

columns
string[] | null

Exact fields to return, plus the lookup fields and RBID_PAO. Omitted, null, or [] returns those identifiers only; ["*"] does not expand on Contact Enrich. Unknown names are ignored. PAYG charges for selected revealed details still apply when their columns are omitted.

reveal
string[] | null

On PAYG, select email (+1 per populated value), mobile (+10), both, or neither ([]), in addition to 1 per returned match. Omitted or null selects both. The hold uses submitted array entries before normalization or deduplication. On AYCE, columns controls returned fields and reveal does not mask them.

Response

Successful Response

The response is of type Response Enrich V1 Enrich Post · object.