Search for contacts

Use the Contact Search API to find business contacts by role, company, and location. Using Count, View, Estimate, and Export lets you check the audience before paying for the records and contact details you need.

Choose the right method

You need	Endpoint	Credits
Matching audience size	Count	0
A masked sample, up to 100 rows	View	0
Audience composition, reachability, freshness, or field fill rates	Insights	0
A forecast before exporting	Estimate	0
Full records returned immediately, up to 50,000	Preview	PAYG retrieval chart
Known contacts, up to 10,000 identifiers	Enrich	PAYG match and detail prices
A downloadable file, up to 1,000,000 rows	Export	PAYG retrieval chart

Reuse the same filter across the steps. To control spend, choose reveal explicitly and set limit for inline records or a positive maxRows for a file. See Which endpoint should I use? for a visual comparison of Count, View, Preview, Insights, and Start Export, with free calls and PAYG credit costs labeled. When rate limiting is active, Contact API responses report the limit through X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. See Rate limits and error codes for retry guidance, and Credits and plans for the prices. AYCE includes unlimited contact retrieval for 0 credits; per-request limits still apply.

Understand the data model

Every record is one person at one company. Person fields and company fields sit on the same record, so a single search can filter on both at once — no joining required. The company search fields also work here. Filter contacts by their company’s size, industry, headquarters, revenue, funding, or technologies, and combine those conditions with a person’s role or location. Company description SmartSearch and look-alike filters are available on contact searches too. See shared company fields for the company-only contact-total exceptions. Column names end in a suffix that tells you what the field describes:

Suffix	Describes	Examples
`_PER`	The person — name, contact details, location	`FULL_NAME_PER`, `EMAIL_ADDRESS_PER`, `COUNTRY_NAME_PER`
`_ORG`	Their company — size, industry, location	`COMPANY_NAME_ORG`, `INDUSTRY_LINKEDIN_ORG`, `EMPLOYEE_COUNT_RANGE_ORG`
`_PAO`	Their job at that company	Role and tenure fields

COUNTRY_NAME_PER is where the person is. For where the company is, use the HEADQUARTERS_* fields — HEADQUARTERS_COUNTRY_NAME_ORG and friends. These are frequently different, so for “people in the United States”, use _PER.

COUNTRY_NAME_ORG is a location the company operates from, not necessarily the head office. For “companies headquartered in the United States”, use HEADQUARTERS_COUNTRY_NAME_ORG. See Company location vs headquarters.

Every field is documented in the Person-Organization-Insight data dictionary, including how each one is sourced and how often it’s populated.

Count matching contacts

Send a filter describing who you want. See Build a search filter for the full syntax.

curl -X POST https://api.revenuebase.ai/v2/contact/count \
  -H "x-key: $REVENUEBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "type": "group",
      "op": "AND",
      "children": [
        {
          "type": "condition",
          "column": "COUNTRY_NAME_PER",
          "operator": "eq",
          "value": "United States"
        },
        {
          "type": "condition",
          "column": "JOB_LEVEL_PER",
          "operator": "eq",
          "value": "VP"
        }
      ]
    },
    "mode": "fast"
  }'

Response captured from the local test API on October 13, 2026. Results can change.

{
  "total": 1318125,
  "companies": 323960,
  "withEmail": 567221,
  "withCellphone": 742003,
  "exact": {
    "total": true,
    "companies": false,
    "withEmail": false,
    "withCellphone": false
  },
  "mode": "fast"
}

The exact object reports which figures are precise. In the default fast mode everything except total is an estimate — display those with a ~. Send "mode": "exact" for precise figures at the cost of a slower response. Counting accounts rather than people? Company Search takes the same filter and returns one row per company.

Preview matching contacts

Preview returns full contact rows inline and is charged on PAYG. Use View for a free masked relevance check. The example below buys email without mobile; see credits.

curl -X POST https://api.revenuebase.ai/v2/contact/preview \
  -H "x-key: $REVENUEBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "type": "group",
      "op": "AND",
      "children": [
        {
          "type": "condition",
          "column": "COUNTRY_NAME_PER",
          "operator": "eq",
          "value": "United States"
        },
        {
          "type": "condition",
          "column": "JOB_LEVEL_PER",
          "operator": "eq",
          "value": "VP"
        }
      ]
    },
    "columns": [
      "RBID_PAO",
      "FULL_NAME_PER",
      "JOB_TITLE_PER",
      "COMPANY_NAME_ORG",
      "EMAIL_ADDRESS_PER"
    ],
    "limit": 2,
    "reveal": [
      "email"
    ]
  }'

Response: Response captured from the local test API on October 13, 2026 using an AYCE account. Results can change.

{
  "rows": [
    {
      "RBID_PAO": "rb-pab23456t-rb-oadkxzpcq",
      "FULL_NAME_PER": "Matthew Tobin",
      "JOB_TITLE_PER": "Senior Vice President Business Development",
      "COMPANY_NAME_ORG": "Ecapital Corp",
      "EMAIL_ADDRESS_PER": "mtobin@ecapital.com"
    },
    {
      "RBID_PAO": "rb-pab2346sr-rb-oacopeifk",
      "FULL_NAME_PER": "Katherine Collins",
      "JOB_TITLE_PER": "AVP of Claim Operations",
      "COMPANY_NAME_ORG": "Travelers",
      "EMAIL_ADDRESS_PER": "katherine.collins@travelers.com"
    }
  ],
  "columns": [
    "RBID_PAO",
    "FULL_NAME_PER",
    "JOB_TITLE_PER",
    "COMPANY_NAME_ORG",
    "EMAIL_ADDRESS_PER"
  ],
  "columnLabels": {
    "RBID_PAO": "Rbid Person And Organization",
    "FULL_NAME_PER": "Person Full Name",
    "JOB_TITLE_PER": "Job Title",
    "COMPANY_NAME_ORG": "Company Name",
    "EMAIL_ADDRESS_PER": "Email Address"
  },
  "rowCount": 2,
  "limit": 2
}

Omit columns to receive a default set. Results are unordered and there is no pagination — preview returns a sample, not page one of a list. For a complete list, use an export.

Understand the response fields

Field	Values	What it means
`total`	integer	Contacts matching the filter. Always exact.
`companies`	integer	Distinct companies represented. Estimated in `fast` mode.
`withEmail`	integer	Matching contacts that have an email address. Estimated in `fast` mode.
`withCellphone`	integer	Matching contacts that have a mobile number. Estimated in `fast` mode.
`exact`	object	Which of the counts above are precise.
`rows`	array	Matching records, one object per contact.
`columns`	array	Column names present in each row, in order.
`columnLabels`	object	Display names for each column, for table headers.
`rowCount`	integer	Rows returned. Never exceeds `limit`.

Export a full list

Exports run asynchronously. First inspect a free View, then estimate the export. Use the same body with an explicit row cap and reveal choice when starting the paid job.

Start the export

Returns an exportId when accepted; acceptance is not completion. This bounded example retrieves up to 100 contacts with email, without mobile. It can reserve up to 200 credits on PAYG before writing the file.

curl -X POST https://api.revenuebase.ai/v2/contact/exports \
  -H "x-key: $REVENUEBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "type": "group",
      "op": "AND",
      "children": [
        {
          "type": "condition",
          "column": "COUNTRY_NAME_PER",
          "operator": "eq",
          "value": "United States"
        },
        {
          "type": "condition",
          "column": "JOB_LEVEL_PER",
          "operator": "eq",
          "value": "VP"
        }
      ]
    },
    "maxRows": 100,
    "reveal": [
      "email"
    ],
    "format": "csv",
    "compression": "gz"
  }'

Save the exportId returned by your start call as REVENUEBASE_EXPORT_ID. Read your actual status response for row counts and the download link.

Poll for status

curl "https://api.revenuebase.ai/v2/contact/exports/$REVENUEBASE_EXPORT_ID" \
  -H "x-key: $REVENUEBASE_API_KEY"

Poll every 5–10 seconds initially and back off for longer jobs. Stop on COMPLETED, ERROR, or CANCELLED. Status calls cost 0 credits.

Download the results

A completed export includes a downloadUrl:Save the exportId returned by your start call as REVENUEBASE_EXPORT_ID. Read your actual status response for row counts and the download link.The link requires no API key and expires after one hour. Treat it as a credential — anyone holding it can download the file. Poll again to get a fresh link.

Track export status

Status	What it means
`QUEUED`	Accepted, not yet started
`PROCESSING`	Writing rows
`COMPLETED`	File ready. `downloadUrl` and row counts are present
`ERROR`	Stop polling. `code` and `error` explain why
`CANCELLING`	Cancellation requested, still winding down
`CANCELLED`	Stopped. No file produced

Manage exports

Endpoint	What it does
`POST /v2/contact/exports`	Start an export. Returns an `exportId`
`GET /v2/contact/exports/{export_id}`	Get current status and the download link
`DELETE /v2/contact/exports/{export_id}`	Cancel an export before it completes

Cancelling an export that has already finished returns its final status unchanged. The complete Export reference explains credit holds, settlement, cancellation, signed-link refresh, and safe retry decisions.

Analyze an audience

POST /v2/contact/insights returns aggregate statistics for a filter instead of rows. Send one section per request.

Section	Returns
`reachability`	How many matching contacts have an email, a mobile number, or both
`freshness`	How recently emails were verified and records updated, in age bands
`coverage`	Contact counts broken down by a field you choose in `groupField`
`fillRate`	How often each field in `fields` is populated

curl -X POST https://api.revenuebase.ai/v2/contact/insights \
  -H "x-key: $REVENUEBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "type": "group",
      "op": "AND",
      "children": [
        {
          "type": "condition",
          "column": "COUNTRY_CODE_PER",
          "operator": "eq",
          "value": "US"
        }
      ]
    },
    "section": "reachability"
  }'

Response: Response captured from the local test API on October 13, 2026. Results can change.

{
  "section": "reachability",
  "reachability": {
    "total": 106956086,
    "withEmail": 24409894,
    "withMobile": 45333156,
    "withBoth": 13864920
  }
}

Match contacts you already have

POST /v2/contact/enrich looks up records for a list of email addresses. Send up to 10,000 addresses per request, counted after canonicalization and de-duplication — 12,000 addresses that resolve to 9,000 distinct ones is fine. Over the cap returns 400; split the list and merge the responses. See Limits.

curl -X POST https://api.revenuebase.ai/v2/contact/enrich \
  -H "x-key: $REVENUEBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "personIds": [
      "rb-pab23456t-rb-oadkxzpcq",
      "rb-pab2346sr-rb-oacopeifk"
    ],
    "columns": [
      "RBID_PAO",
      "FULL_NAME_PER",
      "JOB_TITLE_PER",
      "COMPANY_NAME_ORG",
      "EMAIL_ADDRESS_PER"
    ],
    "reveal": [
      "email"
    ]
  }'

Response: Response captured from the local test API on October 13, 2026 using an AYCE account. Results can change.

{
  "matches": {
    "rb-pab23456t-rb-oadkxzpcq": {
      "RBID_PAO": "rb-pab23456t-rb-oadkxzpcq",
      "FULL_NAME_PER": "Matthew Tobin",
      "JOB_TITLE_PER": "Senior Vice President Business Development",
      "COMPANY_NAME_ORG": "Ecapital Corp",
      "EMAIL_ADDRESS_PER": "mtobin@ecapital.com"
    },
    "rb-pab2346sr-rb-oacopeifk": {
      "RBID_PAO": "rb-pab2346sr-rb-oacopeifk",
      "FULL_NAME_PER": "Katherine Collins",
      "JOB_TITLE_PER": "AVP of Claim Operations",
      "COMPANY_NAME_ORG": "Travelers",
      "EMAIL_ADDRESS_PER": "katherine.collins@travelers.com"
    }
  },
  "columns": [
    "RBID_PAO",
    "FULL_NAME_PER",
    "JOB_TITLE_PER",
    "COMPANY_NAME_ORG",
    "EMAIL_ADDRESS_PER"
  ],
  "matched": 2,
  "total": 2
}

Results are keyed by the address you submitted, so they join directly back to your own list. Addresses with no match are absent from matches; total minus matched is your miss count.

Browse the data

Endpoint	What it does
`GET /v2/contact/columns`	The column catalog. `?include=values` embeds the value lists
`GET /v2/contact/columns/{column}/values`	Values for one enumerable column
`GET /v2/contact/stats`	Table-wide totals: contacts and distinct companies
`GET /v2/contact/match-presets`	The named SmartSearch presets and what each one means
`GET /v2/contact/health`	Service liveness. No API key required

curl https://api.revenuebase.ai/v2/contact/stats \
  -H "x-key: $REVENUEBASE_API_KEY"

Response: Response captured from the local test API on October 13, 2026. Results can change.

{
  "uniqueCompanies": 21337431,
  "contacts": 408446299
}

For what each field contains and how it’s sourced, see the Person-Organization-Insight data dictionary. The catalog tells you which columns exist; the data dictionary tells you what they mean.

Find similar companies

Look-alike search is company-grain, so it lives on the company surface — see Search for companies. You can still use a look-alike leg inside a contact filter to find people at similar companies; see SmartSearch.

Getting Started

Contact API

Contact Endpoints

Company Endpoints

Email API

Utilities

Choose the right method

Understand the data model

Count matching contacts

Preview matching contacts

Understand the response fields

Export a full list

Track export status

Manage exports

Analyze an audience

Match contacts you already have

Browse the data

Find similar companies

Next steps

​Choose the right method

​Understand the data model

​Count matching contacts

​Preview matching contacts

​Understand the response fields

​Export a full list

​Track export status

​Manage exports

​Analyze an audience

​Match contacts you already have

​Browse the data

​Find similar companies

​Next steps

Choose the right method

Understand the data model

Count matching contacts

Preview matching contacts

Understand the response fields

Export a full list

Track export status

Manage exports

Analyze an audience

Match contacts you already have

Browse the data

Find similar companies

Next steps