Prospecting API: build lead lists from contact and company filters
Combine job, company and tech-stack filters in one query, count the matches before you pull, and page through the results into your own tools.
Dag Holmen · Updated · 4 min read
A prospecting API lets you build a prospect list from code. You describe the people you want (title, seniority, function, location) and the companies they should work at (industry, headcount, tech stack), and the API returns the matching contacts as JSON, page by page.
B2Benrich's Prospector endpoint does this in one query. Contact filters and company filters go in the same request, a count endpoint tells you how many people match before you pull anything, and the results come back with the fields you need to dedupe, add emails and load into your own tools.
How the Prospector endpoint works
You send a POST to /v1/search/prospector with your key in the X-Api-Key header. The body has two filter objects and paging:
{
"contact_filters": { "job_level": "VP", "job_function": "Marketing" },
"company_filters": { "technologies": "HubSpot", "employee_count_range": "201-500" },
"include_total_count": true,
"page": 1,
"page_size": 25
}
The response carries records, total_count, total_count_mode, page, page_size, has_more and next_page. Each record is one person with their id, name, linkedin_url, job_title, location and company fields (company_name, company_domain, company_id, industry, company_size, company_revenue).
Contact filters
| Filter | Use it for |
|---|---|
job_title | A specific title, such as "VP of Sales" |
job_level | Seniority, such as VP or Director |
job_function | Department, such as Marketing or Sales |
country_name, state_name | Where the person is based |
Company filters
| Filter | Use it for |
|---|---|
industry_linkedin | The company's industry |
employee_count_range | Headcount band |
technologies | A tool in the company's tech stack |
hq_country | Where the company is headquartered |
Job level and function are usually better than exact titles. Titles are messy ("VP Marketing", "Vice President, Marketing", "VP of Growth Marketing"). Level plus function catches all of them, and you can add job_title later if the list is too broad.
Step 1: get the exact filter values
Filters match exact values, so look them up first. The meta endpoint returns every allowed value for a field:
curl --request POST \
--url https://api.b2benrich.com/v1/search/meta/job_level \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: YOUR_API_KEY' \
--data '{ "page": 1 }'
You get back values (each with a value) and has_more. Do the same for job_function, industry_linkedin, employee_count_range and technologies. Store the lists and check your filters against them in code, so a typo fails loudly instead of returning zero results.
Step 2: count before you pull
/v1/search/prospector/count takes the same filters and returns only the count:
curl --request POST \
--url https://api.b2benrich.com/v1/search/prospector/count \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: YOUR_API_KEY' \
--data '{
"contact_filters": { "job_level": "VP", "job_function": "Marketing" },
"company_filters": { "technologies": "HubSpot" }
}'
{ "total_count": 4820 }
Use it to tune the query. Too few matches: drop a filter or widen the headcount band. Too many: add a region or a size band. A few count calls cost you seconds and save you from paging through a list you'd throw away.
Step 3: page through the results
Once the count looks right, loop until has_more is false. This Node script writes one JSON object per line and skips anyone it has already seen:
import fs from 'node:fs';
const BASE = 'https://api.b2benrich.com';
const body = {
contact_filters: { job_level: 'VP', job_function: 'Marketing' },
company_filters: { technologies: 'HubSpot', employee_count_range: '201-500' },
page_size: 100
};
const seen = new Set();
const out = fs.createWriteStream('prospects.jsonl');
let page = 1;
while (true) {
const res = await fetch(`${BASE}/v1/search/prospector`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-Api-Key': process.env.B2BENRICH_KEY },
body: JSON.stringify({ ...body, page })
});
if (!res.ok) throw new Error(`Page ${page} failed: ${res.status}`);
const data = await res.json();
for (const r of data.records) {
if (seen.has(r.id)) continue;
seen.add(r.id);
out.write(JSON.stringify(r) + '\n');
}
if (!data.has_more) break;
page = data.next_page ?? page + 1;
}
out.end();
Save the filter JSON next to the output file. When someone asks "where did this list come from?", the answer is a file, not a memory.
Step 4: add emails and load the list
Prospector records don't include email addresses. For each person, call /v1/enrich/person/name-domain-to-email with first_name, last_name and company_domain as the domain. The email finder API guide covers that call and how to run it across a list. Then dedupe against your CRM on LinkedIn URL or email and push the new rows to your sequencer or CRM.
Prospector vs the other search endpoints
Prospector is the broad search. The others are faster paths for narrower questions.
| Situation | Endpoint |
|---|---|
| People across many companies, by role and company traits | /v1/search/prospector |
| Everyone (or one function) at one company you already picked | /v1/search/company-employees |
| A given title at a company you know by name | /v1/search/title-company |
| You want to describe the list in a sentence | /v1/search/ai |
| You need the companies first, not the people | /v1/search/companies |
The AI search is a good way to start. It returns records plus the prospector_search it built from your sentence, which you can paste into a Prospector request and page through properly. For per-company searches see the people search API guide. For account-first lists see the company search API guide, and for stack-based targeting, technographic data.
Rerun it, don't rebuild it
A prospect list goes stale as people change jobs. Because the query is code, keeping it current is a cron job: rerun the same filters weekly, compare the new id set with last week's, and route only the new people to outreach. With B2Benrich that costs nothing extra. It's one plan, unlimited API usage for $500 a month, with no credits.
Frequently asked questions
- What is a prospecting API?
- A prospecting API returns contacts that match filters you send, such as job level, function, location, company industry, headcount and tech stack. You call it from code and get structured records back, so you can build and refresh prospect lists without a UI.
- How do I build a lead list with an API?
- Look up exact filter values with the meta endpoint, size the list with the count endpoint, then page through the search results and save them. Dedupe on the record ID, add work emails, and load the rows into your CRM or sequencer.
- How do I know how many contacts match before I pull them?
- Send the same filters to /v1/search/prospector/count. It returns only the total, so you can adjust filters until the list is the size you want.
- Can I filter prospects by the tools their company uses?
- Yes. Put a technologies value in company_filters, for example HubSpot. Use /v1/search/meta/technologies to get the exact names.
- Does the Prospector return email addresses?
- No. It returns names, titles, LinkedIn URLs, location and company fields. Get work emails with the name-domain-to-email endpoint, using each person’s first name, last name and company domain.
- What’s the difference between Prospector and AI search?
- Prospector takes structured filters. AI search takes a sentence and returns matches plus the structured search it built. Many builders start with AI search, then reuse its filters in Prospector for repeatable, paged pulls.
Related guides
- People search API: find contacts by title, company and locationSearch for people by job title, company, seniority and location, list everyone at a company, or describe who you want in plain English.
- Company search API: find accounts by industry, size and locationSearch companies by name, industry, headcount, revenue, location and founding year, and turn the results into an account list.
- Technographic data: find companies by the tools they useWhat technographic data is, the tech-stack categories you can filter on, and how to build a list of companies that use, or don’t use, a given tool.