Which endpoint should I use?
Choose a Reverse Contact API endpoint for profile lookup, enrichment, search, contacts or bulk processing, with costs and sync or async delivery.
The right Reverse Contact endpoint depends on the data you start from: a Social URL, an email or a name, search filters, or a sentence that describes the people or companies you want. Find your starting point below.
Pick your starting point
- You have a Social URL: get the full profile
- You have an email, a name or a domain: find the matching profile
- You have filters such as a job title or a location: search our database
- You can describe the people you want in a sentence: Agentic Search
- You are building a people search box in your own product: Search autocomplete for your product
- You can describe the companies you want in a sentence: Agentic Company Search
- You need a professional or personal email address: find an email
- You have a CSV file of contacts: Enrich a CSV file, or send its rows in one request with Bulk
Profiles
Turn a Social URL into a person or company profile.
| Endpoint | Credits | Delivery | When to use |
|---|---|---|---|
POST /v2/fetch/persons/check | 0 | Sync | Check if a person profile exists before spending credits |
POST /v2/fetch/companies/check | 0 | Sync | Check if a company profile exists before spending credits |
POST /v2/fetch/persons | 1 | Sync | Retrieve a cached person profile. Fast and cheap |
POST /v2/fetch/companies | 1 | Sync | Retrieve a cached company profile. Fast and cheap |
POST /v2/fetch/persons/live | 2 | Async | Force a fresh scrape when you need the latest data |
POST /v2/fetch/companies/live | 2 | Async | Force a fresh scrape when you need the latest data |
Enrichment
Find a profile when you don't have a Social URL. Send the details you have and get the full profile back in the same response.
| Endpoint | Credits | Delivery | Input |
|---|---|---|---|
POST /v2/enrich/persons | 2 | Sync | Any combination of email, name, company name or domain |
POST /v2/enrich/companies | 2 | Sync | A company domain (e.g. acme.com) |
Search
Query our database of indexed profiles with filters. No Social URL needed.
| Endpoint | Credits | Delivery | When to use |
|---|---|---|---|
POST /v2/search/people | 1 per profile | Sync | Search people by function, seniority, title, location, company... |
POST /v2/search/people/prompt | 1 per page + 1 per profile | Sync | Describe the people you want in plain language instead of building filters |
POST /v2/search/people/count | 0 | Sync | Count matching people before spending credits |
POST /v2/search/people/auto-completion-fields | 0 | Sync | Complete a job title, company, school, skill, city, industry or country as someone types, in a search box of your own product |
POST /v2/search/organizations | 1 per company | Sync | Search companies by industry, specialities, size, founding year, location... |
POST /v2/search/organizations/prompt | 1 per page + 1 per company | Sync | Describe the companies you want in plain language instead of building filters |
POST /v2/search/organizations/count | 0 | Sync | Count matching companies before spending credits |
Contact
Find a professional or personal email address from a Social profile URL, or from a person's full name and company domain. Check an address you already have before you send to it.
| Endpoint | Credits | Delivery | When to use |
|---|---|---|---|
POST /v2/contact/email | 3 professional, 5 personal, when found | Async | Find a professional (default) or personal email address with emailType |
POST /v2/contact/email/verify | 1 per verdict | Async | Check whether an address you already have can receive mail: valid, risky, invalid or unknown |
Lists
Keep people or companies in a List you fill over time, and buy their emails, phone numbers and profiles in one import. See Lists, then Build your first List.
| Endpoint | Credits | Delivery | When to use |
|---|---|---|---|
POST /v2/lists/:listId/members | 1 or 2 per new member | Sync | Add up to 1,000 people or companies and get one result per Signal |
POST /v2/lists/:listId/intake/signals | Per new member and per family bought, up to maxCredits | Async | Import up to 25,000 Signals, or a public CSV file or Google Sheet, and buy emails, phones, profiles or company details |
GET /v2/lists/:listId/export | 0 | Sync | Download the members with the data the List holds, and the Pending Intake lines with what was sent, as CSV or NDJSON |
Bulk
Send up to 25,000 people in one request and get one CSV row per person back, without keeping them in a List. See Enrich people in bulk.
| Endpoint | Credits | Delivery | When to use |
|---|---|---|---|
POST /v2/bulk | Per item, as its unit call, only when found | Async | Enrich a file of people once: profiles, emails or phone numbers |
GET /v2/tasks/:taskId/results | 0 | Sync | Download the results CSV once the task is completed or cancelled |
Sync vs async
Most endpoints return data instantly in the API response. Live endpoints, Find Email, a List import and Bulk deliver their results asynchronously.
| Delivery | How it works |
|---|---|
| Async | Results pulled on demand via polling, or pushed to your webhook URL. A List import is followed at its pollUrl instead, and a Bulk task at GET /v2/tasks/:taskId, each with its own webhookUrl |
| Sync | Instant JSON response |
FAQ
Should I use the cached Fetch endpoint or the Live endpoint for profiles?
POST /v2/fetch/persons and POST /v2/fetch/companies return a cached profile synchronously for 1 credit, while POST /v2/fetch/persons/live and POST /v2/fetch/companies/live force a fresh scrape for 2 credits and deliver the result asynchronously. The recommended flow is to call the free Check endpoint first (POST /v2/fetch/persons/check or POST /v2/fetch/companies/check), then Fetch if the record is recent, or Live if it's missing or stale. See Data freshness.
How much does people or company search cost?
POST /v2/search/people returns full profiles and costs 1 credit per profile delivered, so size a query first with POST /v2/search/people/count, which costs 0 credits. POST /v2/search/organizations works the same way for companies: 1 credit per company delivered, sized for free with POST /v2/search/organizations/count.
How do I find a professional email address, and what does it cost?
Use POST /v2/contact/email (Find Email) with a Social profile URL, or with a person's full name and company domain. Find Email delivers its result asynchronously, by polling or webhook, and finds professional emails by default; set emailType to personal for a personal address, or to any to accept either. Find Email is billed only when an email is found, on the kind of email found: 3 credits for a professional email and 5 credits for a personal email, so an any lookup costs 3, 5 or 8 credits (8 only when it finds both).
Which Reverse Contact endpoints are asynchronous?
Live endpoints and Find Email deliver their results asynchronously, while most other endpoints return data instantly in the API response. Live endpoint results can be pulled on demand with polling (no setup, no public endpoint, free to call) or pushed to a webhook URL. See Polling. A List import and a Bulk task are asynchronous too: a List import is read at its pollUrl, and a Bulk task at GET /v2/tasks/:taskId, both for free.
Last verified