Search for contacts

Use the Contact Search API to find business contacts by role, company, and location — count how many match, preview a sample, then export the full list.

Choose the right method

	Preview	Export
Use when	Checking that a search returns the right people	Pulling a full list to load somewhere else
Endpoint	`POST /v2/contact/preview`	`POST /v2/contact/exports`
Response	Immediate, up to 50,000 rows	Async — poll job status, then download results
Best for	Interactive search, sanity checks	Bulk extracts, CRM and outreach loads

Count before you do either. POST /v2/contact/count is immediate and tells you whether a search is worth running. Every response carries the standard X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. See Rate limits and error codes, and Credits & Plans for what searches and downloads cost on your plan.

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. 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: {YOUR_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": "in", "valueList": ["VP", "C-Level"] }
      ]
    }
  }'

Response:

{
  "total": 2410220,
  "companies": 574874,
  "withEmail": 908255,
  "withCellphone": 412008,
  "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

Return rows inline to check a search before committing to an export.

curl -X POST https://api.revenuebase.ai/v2/contact/preview \
  -H "x-key: {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { ... },
    "limit": 20,
    "columns": ["FULL_NAME_PER", "JOB_TITLE_PER", "COMPANY_NAME_ORG", "EMAIL_ADDRESS_PER"]
  }'

Response:

{
  "rows": [
    {
      "FULL_NAME_PER": "Dana Whitfield",
      "JOB_TITLE_PER": "VP of Marketing",
      "COMPANY_NAME_ORG": "Northwind Analytics",
      "EMAIL_ADDRESS_PER": "dana.whitfield@northwind.com"
    }
  ],
  "columns": ["FULL_NAME_PER", "JOB_TITLE_PER", "COMPANY_NAME_ORG", "EMAIL_ADDRESS_PER"],
  "columnLabels": { "FULL_NAME_PER": "Full Name" },
  "rowCount": 20,
  "limit": 20
}

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. Submit the search, poll for status, then download the file.

Start the export

Returns an exportId immediately. Formats are csv, json, and parquet; compression is gz, zip, or none.

curl -X POST https://api.revenuebase.ai/v2/contact/exports \
  -H "x-key: {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"filter": { ... }, "format": "csv", "compression": "gz"}'

{ "exportId": "exp_9c2f1a", "status": "QUEUED", "format": "csv",
  "compression": "gz", "maxRows": 1000000 }

Poll for status

curl https://api.revenuebase.ai/v2/contact/exports/{EXPORT_ID} \
  -H "x-key: {YOUR_API_KEY}"

Poll until status is COMPLETED. Use a reasonable interval — every 5–10 seconds for smaller exports.

Download the results

A completed export includes a downloadUrl:

{ "exportId": "exp_9c2f1a", "status": "COMPLETED", "rowCount": 100000,
  "bytes": 184320512, "compressedBytes": 41287168,
  "downloadUrl": "https://...", "expiresInSeconds": 3600 }

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
`FAILED`	Stopped with an error. `error` explains 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.

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: {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"filter": { ... }, "section": "reachability"}'

Response:

{
  "section": "reachability",
  "reachability": { "total": 2410220, "withEmail": 908255,
                    "withMobile": 412008, "withBoth": 311947 }
}

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: {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["dana.whitfield@northwind.com"],
       "columns": ["JOB_TITLE_PER", "COMPANY_NAME_ORG"]}'

Response:

{
  "matches": {
    "dana.whitfield@northwind.com": {
      "EMAIL_ADDRESS_PER": "dana.whitfield@northwind.com",
      "JOB_TITLE_PER": "VP of Marketing",
      "COMPANY_NAME_ORG": "Northwind Analytics"
    }
  },
  "columns": ["EMAIL_ADDRESS_PER", "JOB_TITLE_PER", "COMPANY_NAME_ORG"],
  "matched": 1,
  "total": 1
}

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: {YOUR_API_KEY}"

Response:

{ "uniqueCompanies": 14762388, "contacts": 682104553 }

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