> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revenuebase.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Search for contacts
> Count, preview, and export B2B contacts by role, company, and location using the v2 Contact Search API.
export const RBCardGroup = ({cols = 3, children}) =>
}
{tag && {tag}}
;
};
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](/api-reference/v2/rate-limits), and [Credits & Plans](/api-reference/v2/credits) 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](/api-reference/v2/contact-api-overview#company-location-vs-headquarters).
Every field is documented in the [Person-Organization-Insight data dictionary](/docs/data-features/pre-joined-tables/person-organization-insight), 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](/api-reference/v2/search-filters) for the full syntax.
```bash theme={null}
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:**
```json theme={null}
{
"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](/api-reference/v2/company-search-overview) 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.
```bash theme={null}
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:**
```json theme={null}
{
"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.
Returns an `exportId` immediately. Formats are `csv`, `json`, and `parquet`; compression is `gz`, `zip`, or `none`.
```bash theme={null}
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"}'
```
```json theme={null}
{ "exportId": "exp_9c2f1a", "status": "QUEUED", "format": "csv",
"compression": "gz", "maxRows": 1000000 }
```
```bash theme={null}
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.
A completed export includes a `downloadUrl`:
```json theme={null}
{ "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 |
```bash theme={null}
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:**
```json theme={null}
{
"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](/api-reference/v2/contact-api-overview#limits).
```bash theme={null}
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:**
```json theme={null}
{
"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 |
```bash theme={null}
curl https://api.revenuebase.ai/v2/contact/stats \
-H "x-key: {YOUR_API_KEY}"
```
**Response:**
```json theme={null}
{ "uniqueCompanies": 14762388, "contacts": 682104553 }
```
For what each field contains and how it's sourced, see the [Person-Organization-Insight data dictionary](/docs/data-features/pre-joined-tables/person-organization-insight). 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](/api-reference/v2/company-search-overview). You can still use a look-alike leg inside a contact filter to find *people* at similar companies; see [SmartSearch](/api-reference/v2/smartsearch).
## Next steps