> ## 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.
# The Contact API
> Search RevenueBase's verified contact graph by meaning — count, preview, and export people and the companies they work at.
export const RBCardGroup = ({cols = 3, children}) =>
}
{tag && {tag}}
;
};
The Contact API puts the RevenueBase contact graph behind a single search endpoint. Describe who you're looking for — by role, by what their company does, or by resemblance to an account you already have — and get back people, companies, or a file.
It's the same data as the [data feeds](/docs/data-feeds/overview), queried live instead of delivered monthly.
## What one record is
Every record the API returns is a **pre-joined contact**: one person, at one company, with that company's firmographics and insights already attached. There is no join to write and no second call to make.
Person
Name · email · phone
\_PER
+
Their job
Title · seniority · tenure
\_PAO
+
Their company
Size · industry · location
\_ORG
↓
One row returned by the API
Filter on any of the three at once — no join required
That is why a single filter can say "VPs of Marketing **at** software companies **with** 200–500 employees **in** the US" without touching more than one endpoint.
## Read a column name
The suffix on every column tells you which part of the record it describes. Learn this one thing and the whole API opens up.
| Suffix | Describes | Examples |
| ------ | ------------------------- | ----------------------------------------------------------------------- |
| `_PER` | The person | `FULL_NAME_PER`, `EMAIL_ADDRESS_PER`, `COUNTRY_NAME_PER` |
| `_ORG` | Their company | `COMPANY_NAME_ORG`, `INDUSTRY_LINKEDIN_ORG`, `EMPLOYEE_COUNT_RANGE_ORG` |
| `_PAO` | Their job at that company | Role and tenure fields |
**Developer rule of thumb**
`COUNTRY_NAME_PER` is where the **person** is. For where the **company** is, use the `HEADQUARTERS_*` fields. These are frequently different. For "people in the United States", you almost always want `_PER`.
These map directly onto the identifiers used across the data feeds — `RBID_PER` for the person, `RBID_ORG` for the company, `RBID_PAO` for this person at this company. See [Data Overview](/docs/data-feeds/overview) for the full model, and the [Person + Organization + Insights](/docs/data-features/pre-joined-tables/person-organization-insight) data dictionary for every field.
### Company location vs headquarters
Companies operate from more than one place, and the field you pick decides which one you get.
| Fields | What they hold |
| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `HEADQUARTERS_CITY_ORG`, `HEADQUARTERS_STATE_NAME_ORG`, `HEADQUARTERS_COUNTRY_NAME_ORG` | **The company's headquarters.** Use these for a company address. |
| `CITY_ORG`, `STATE_NAME_ORG`, `COUNTRY_NAME_ORG` | *A* location the company operates from — sometimes the headquarters, sometimes not. |
| `LOCATION_COUNT_ORG` | How many locations the company lists. |
Filtering on `COUNTRY_NAME_ORG` when you meant the head office quietly returns companies whose HQ is somewhere else. For "companies headquartered in the United States", use `HEADQUARTERS_COUNTRY_NAME_ORG`.
The non-HQ location fields hold a single value today and will become arrays of multiple locations in a future release. Filter on `HEADQUARTERS_*` wherever you need a stable, single answer.
## Two ways to search
Both read the same graph. What changes is the grain of a row.
| | Contact Search | Company Search |
| -------------------- | --------------------------------------- | --------------------- |
| **A row is** | One person, with their company attached | One company |
| **Fields available** | Person, job, **and** company | Company only |
| **Ask it for** | People to contact | Accounts to target |
| **Base path** | `/v2/contact` | `/v2/contact/company` |
**Contact Search is the main surface.** It returns the whole record — person fields and company fields together — so most work starts and ends here.
**Company Search is a focused subset of the same data.** Same filter object, same workflow, but one row per company and company fields only. Reach for it when you want an account list rather than a people list, or a count of companies rather than a count of people.
Company Search rejects person fields (`_PER`, `_PAO`) and job title SmartSearch with a `422` that names the fix. A company row has no person on it, so there is nothing for those filters to match.
## Start in three minutes
Every request takes an API key in the `x-key` header. Grab yours from **Developers** in the [dashboard](https://app.revenuebase.ai).
```bash theme={null}
export KEY="{YOUR_API_KEY}"
export API="https://api.revenuebase.ai/v2/contact"
```
```bash theme={null}
curl "$API/stats" -H "x-key: $KEY"
```
```json theme={null}
{ "uniqueCompanies": 14762388, "contacts": 682104553 }
```
Marketing leaders at US software companies — described, not keyword-matched.
```bash theme={null}
curl -X POST "$API/count" \
-H "x-key: $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": "semantic", "on": "title",
"text": "runs demand generation", "match": "similar" }
]
}
}'
```
```json theme={null}
{ "total": 41208, "companies": 18774, "withEmail": 33012,
"withCellphone": 11409, "mode": "fast" }
```
Swap `count` for `preview` and add a row limit. If the people look right, swap it for `exports` and take the whole list as a file.
## What makes it different
Most contact APIs match characters. A title list of twenty entries misses the forty spellings you didn't think of, and `contains "marketing"` returns Marketing Interns.
**SmartSearch matches meaning.** Describe a role, describe what a company does, or point at a company you already like — and combine all three in one query, with ordinary filters alongside. Nothing else in this market lets you put five look-alike companies, two job-title searches, and an exclusion in the same request.
## The workflow
Count, look, then pull. In that order, every time — counting is instant and free of surprises; exporting a million rows is not.
| Step | Endpoint | Answers |
| -------------- | -------------------------- | ------------------------------------------- |
| **1. Count** | `POST /v2/contact/count` | Is this roughly the right number of people? |
| **2. Preview** | `POST /v2/contact/preview` | Do these look like the right people? |
| **3. Export** | `POST /v2/contact/exports` | Give me the whole list as a file |
Up to 50,000 rows come back inline from preview. Anything larger goes through an export, which runs in the background and hands you a download link.
## Limits
Everything the API caps, in one place. Both surfaces share these unless a row says otherwise.
### What you send
| Limit | Value | Exceeding it |
| ------------------------------------------------------ | ----------------------------------------------------- | ------------ |
| Email addresses per `enrich` call | **10,000** | `400` |
| Domains + LinkedIn URLs per company `enrich` call | **10,000** combined | `400` |
| Values in one `in` or `notIn` list | **50,000** | `422` |
| Values across every `in` / `notIn` list in one request | **50,000** | `422` |
| Conditions per filter | 25 | `422` |
| Filter nesting depth | 8 | `422` |
| Job title SmartSearch nodes per filter | 3 | `422` |
| Company description SmartSearch nodes per filter | 3 | `422` |
| Look-alike SmartSearch nodes per filter | 10 | `422` |
| SmartSearch `text` length | 300 characters | `422` |
| Export `filename` | 150 characters, letters/digits/spaces and `. _ ( ) -` | `400` |
Both enrich caps are counted **after de-duplication and canonicalization**. Sending 12,000 email addresses that resolve to 9,000 distinct ones is fine. For company enrich, the cap spans both lists together — 6,000 domains plus 5,000 LinkedIn URLs is over it.
The two `in` list caps are separate and both apply. A single clause may carry 50,000 values, **and** every `in` and `notIn` clause in the filter adds up to at most 50,000 — so four `OR`-ed clauses of 20,000 each is rejected even though no single clause exceeds the cap.
Over a cap? Split the input and merge the responses. Both `enrich` endpoints key their results by the value you sent, so merging is a dictionary update — no re-matching required.
### What you get back
| Limit | Value | Notes |
| --------------------------- | ----------------------------- | ------------------------------------------------------------------------------------- |
| Preview rows | **50,000** max, 1,000 default | A higher `limit` is clamped, not rejected |
| Export rows | **1,000,000** max | Lower it with `maxRows` |
| Look-alike endpoint results | **No limit** | Bounded by the similarity floor instead; omit `limit` and you get everything above it |
| Distinct values per column | The column's own `valueLimit` | Multiselect columns only; read it from `/v2/contact/columns` |
| Export download link | 1 hour | Poll the export again for a fresh one |
### Rate limits
Requests are limited per API key in a fixed one-second window. Over the limit returns `429`; every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. See [Rate limits and error codes](/api-reference/v2/rate-limits) and [Credits & Plans](/api-reference/v2/credits).
## Where to go next