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
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.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.RBID_PER for the person, RBID_ORG for the company, RBID_PAO for this person at this company. See Data Overview for the full model, and the Person + Organization + Insights 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.
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 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
1
Set your key
Every request takes an API key in the
x-key header. Grab yours from Developers in the dashboard.2
Prove it works
3
Size an audience
Marketing leaders at US software companies — described, not keyword-matched.
4
Look at who you got
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, andcontains "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.
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
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.
What you get back
Rate limits
Requests are limited per API key in a fixed one-second window. Over the limit returns429; every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. See Rate limits and error codes and Credits & Plans.