B2B Leads API Search Filters: A Reference for Turning ICP Criteria Into Query Parameters

Most teams that buy a B2B leads API spend their first month on authentication, retries, and webhook plumbing. That work matters, but it is not where lists succeed or fail. The difference between a pipeline that produces 400 qualified accounts a week and one that burns credits on empty segments almost always comes down to filter design.

The gap is easy to describe. Your ICP lives in a slide deck as prose: "mid-market SaaS companies in North America with 200–2,000 employees, a VP of Sales or Head of Revenue, running Salesforce and Outreach, that raised a Series B in the last 18 months." The API expects discrete, typed parameters with controlled vocabularies. Translating one into the other is a skill, and it is the skill this reference is built around.

Salesforce's own guidance on B2B lead generation strategy keeps returning to the same point: targeting precision beats volume. In an API context, precision is not a marketing philosophy — it is a set of parameters. Broad exports feel productive because they return rows. Filtered queries feel slow because they return fewer rows. The filtered query is the one that converts.

Treat this as a reference, not a tutorial. Each section maps one ICP dimension onto concrete query fields, notes where the mapping breaks, and gives you a pattern you can copy into your own client.

Firmographics are the most stable filters you have. Company size, industry, and revenue change slowly, which makes them safe anchors for a query you intend to reuse every week. The trap is assuming every provider uses the same taxonomy. Industry labels in particular vary wildly between vendors, and a filter value that returns 12,000 companies in one dataset can return 400 in another.

Two practical rules. First, prefer ranges over exact values — exact employee counts are frequently stale or rounded, so employee_range with a band will match more records than employee_count: 450. Second, layer company type as an exclusion rather than an inclusion when your goal is to remove noise. Excluding public companies and nonprofits from a mid-market SMB query usually removes more junk than adding three industry labels removes.

People filters are where most queries quietly break. Titles are free text in the real world and controlled vocabularies in the API, and the two rarely line up. "VP Sales," "Head of Revenue," "CRO," and "Chief Revenue Officer" can all describe the same buyer at different companies, and a strict title match will find one of them.

HubSpot's writing on sales prospecting makes the same observation from the rep's side: the buyer definition has to be broad enough to be findable and narrow enough to be relevant. In API terms, that means combining three fields rather than relying on one.

• Department — department: ["sales", "revenue_operations"]. The most reliable people filter. Departments are normalized far more consistently than titles.
• Seniority — seniority: ["vp", "c_suite", "director"]. Use this to control budget authority without guessing at exact titles.
• Title keywords — title_contains: ["revenue", "sales"]. A substring match that catches variants a strict list would miss.
• Title exclusions — title_exclude: ["assistant", "intern", "coordinator"]. Cheap insurance against junior contacts in senior-looking departments.

The normalization caveat is worth stating plainly: no provider normalizes titles perfectly. If your campaign depends on reaching a specific function, build the query around department plus seniority and treat the title field as a refinement, not the primary key. You will get a slightly noisier list that is materially larger — often enough that you can filter the remainder during enrichment or in your sequencing tool without losing the segment.

Geography looks simple and is not. The three decisions that matter are granularity, headquarters versus branch, and how location interacts with your other filters.

Granularity runs from country down to metro area. Country and state/region filters are well supported almost everywhere. Metro and postal-code filters are supported inconsistently, and when they exist they often rely on a provider-specific metro definition. If your ICP is "US and Canada," use country. If it is "the Bay Area," test the metro filter against a known-good list of companies before you trust it.

Headquarters versus branch is the decision that quietly ruins lists. A filter on location may match any office a company has, which means a query for "Germany" can return a US-headquartered company with a Berlin sales office. If you are targeting decision-makers, use hq_country and hq_state instead of the general location field. If you are targeting field teams or regional operators, the general field is correct.

One more interaction to watch: geography multiplies against every other filter. Adding a country filter to an already narrow query — small industry set, narrow revenue band, specific tech stack — can sharply reduce your result count, often by an order of magnitude in practice. That is not a bug, but it is a signal that your segment is too tight to sustain weekly delivery.

Technographic and signal filters are the most valuable and the least stable. Value comes from specificity: "runs HubSpot and has a sales team of 20+" is a far better qualifier than "is in software." Instability comes from the fact that these signals decay.

The operational rule: stable filters belong in your base query, time-sensitive filters belong in a separate trigger query. Mixing them means your recurring list silently degrades as the signal ages out, and you will not notice until reply rates drop. Keep a base segment of firmographic and role filters, then layer signals on top for campaign-specific pulls.

Filter combination is where queries become either precise or empty. Most B2B leads APIs follow a predictable convention, and knowing it saves hours of debugging.

• Across fields, the default is AND. industry plus employee_range plus country means all three must match.
• Within a field, arrays are OR. industry: ["software", "fintech"] matches either.
• Exclusions are separate fields. tech_exclude, title_exclude, company_type_exclude — they subtract rather than add.
• Explicit OR groups are usually nested objects. When you need "either (SaaS and 200+ employees) or (fintech and 50+ employees)," that requires an or array of condition objects, not a flat parameter list.

A combined query for mid-market SaaS revenue leaders running Salesforce looks roughly like this:

<code>{
  "industry": ["software", "information_technology"],
  "employee_range": { "min": 200, "max": 2000 },
  "hq_country": ["US", "CA"],
  "company_type_exclude": ["public", "nonprofit"],
  "department": ["sales", "revenue_operations"],
  "seniority": ["vp", "c_suite", "director"],
  "title_exclude": ["assistant", "intern", "coordinator"],
  "tech_stack": ["salesforce"],
  "limit": 25
}</code>

Note the limit: 25. Never run a new filter combination at full page size. A 25-record test tells you whether the segment exists and whether the contacts look right, at a fraction of the cost of a 1,000-record pull.

The single highest-leverage habit in programmatic list building is previewing before exporting. A preview endpoint returns an estimated match count and often a small sample without consuming export credits. That turns filter design from a guessing game into a measurement loop.

You can run the same discipline manually through previewing lead counts before you spend credits, and the logic is identical whether you are clicking or calling an endpoint:

1. Build the base query with firmographic and role filters only. Preview it. If the count is under a few hundred, the segment is too narrow to sustain.
2. Add one filter at a time and re-preview. The count drop after each addition tells you which filter is doing the real work.
3. If a filter removes 95% of results, check the taxonomy before you accept it. A misspelled industry label or an unsupported tech name will look exactly like a genuinely tiny market.
4. Pull a 10–25 record sample and read the actual records. Counts tell you the segment exists; samples tell you it is the right segment.
5. Only then run the full export, and cap it at what you can work in one campaign cycle.

Salesforce's lead management implementation guide frames the same principle from the CRM side: lead data entering a system should be validated at intake, not cleaned after it has polluted reporting. Preview is intake validation for API-sourced lists.

Pagination behaves differently once filters are in play, because the result set is no longer a stable, fully materialized list. Two things change.

First, page size and filter breadth interact. A narrow query with 400 total matches does not need cursor pagination — a single request with a generous limit is simpler and cheaper. A broad query with 200,000 matches absolutely does, because offset pagination on a large filtered set gets slower with every page and can skip or duplicate records if the underlying data shifts between requests.

Second, rate limits are usually per-request, not per-record. That means many small pages cost more against your limit than fewer large pages, but large pages risk timeouts on complex filter combinations. A practical default is 100 records per page for filtered queries, dropping to 25 for queries with three or more signal filters.

Cursor-based pagination is the safer choice for anything you intend to run repeatedly, since it is resilient to records being added or removed mid-pull. Offset pagination is fine for one-off exports under a few thousand records. For a deeper treatment of page-size tradeoffs, retry behavior, and how to resume an interrupted pull without duplicating records, see the API security and data access best practices reference for adjacent operational guidance.

Three patterns cover most production use cases. Each is a starting template — adjust the values, keep the structure.

Goal: consistent weekly volume of revenue leaders at growing software companies.

• industry: ["software", "information_technology"]
• employee_range: {min: 200, max: 2000}
• hq_country: ["US", "CA", "GB"]
• department: ["sales", "revenue_operations"], seniority: ["vp", "c_suite", "director"]
• headcount_growth_6m: {min: 0.10} — the growth signal keeps the list fresh without a hard event dependency

Rationale: firmographics and role are stable, so the query can run on a schedule. Growth replaces funding as a signal because it fires continuously rather than in bursts.

Goal: a parameterized template that one query shape can serve across many client accounts.

• Store the client's ICP as a JSON config: industry array, size band, country array, department, seniority.
• Keep the query structure identical across clients; only the config values change.
• Add a per-client exclude_domains list so previously delivered accounts never repeat.
• Run preview first, then export at a fixed page size so credit consumption is predictable per client.

Rationale: agencies win on repeatability. One query shape with swappable config is maintainable; twenty bespoke queries are not. The reference on agency lead list credit management goes deeper on how to forecast and track credit usage across multiple clients running exactly this template.

Goal: fill gaps in an existing CRM rather than source net-new accounts.

• Export your CRM's incomplete records as a domain or company-name list.
• Query by domain or company_name in batches, not by ICP filters — you already know who you want.
• Request only the fields you are missing, and map responses to CRM fields deliberately rather than dumping the full payload.
• Log which records matched and which did not, so unmatched accounts become a separate sourcing problem.

Rationale: enrichment is a lookup problem, not a search problem. Mixing the two produces duplicate records and muddy attribution. Field-level mapping decisions are covered in the reference on contact enrichment API error codes and troubleshooting, which pairs naturally with a RevOps enrichment workflow.

Use this as a pre-flight checklist before any production pull.

• Empty results from a valid-looking query. Usually a taxonomy mismatch. Test each filter value individually against a known-good company to confirm the label exists.
• Over-broad segments. If your preview returns six figures, your filters are not doing work. Add a department or seniority constraint before adding more industry labels.
• Title mismatches. Strict title lists under-return. Switch to department plus seniority plus title_contains.
• Geographic ambiguity. Using a general location field when you meant headquarters. Switch to hq_* fields.
• Exclusion logic errors. Excluding a company type that was never included in the first place, or excluding a tech that overlaps with a required tech, producing zero results.
• Credit burn from un-validated queries. Running full exports on untested filter combinations. Always preview, always sample, always cap the first pull.
• Stale signal filters. Leaving a funding or hiring filter in a recurring query. Move time-sensitive filters to campaign-specific queries.

When a query fails in a way that does not match any of these, the failure is usually in the request layer rather than the filter layer — malformed nested objects, wrong types on range fields, or an unsupported parameter being silently ignored. Silent ignoring is the dangerous one, because the query succeeds and returns the wrong segment.

Filter design is the part of API work that compounds. A well-built base query, validated with previews and paginated correctly, can run for months with minor tuning. A sloppy one produces a new debugging session every time someone changes a segment.

The discipline is short: map each ICP dimension to a specific parameter, keep stable filters separate from time-sensitive ones, preview before you export, sample before you scale, and paginate according to the size of the filtered result set rather than a fixed default.

If you want to see the full parameter surface — firmographic, role, location, technographic, and signal fields — along with a sandbox to test combinations against real counts, start with the B2B leads API. Build one query, preview it, and adjust until the count and the sample both look right. That first validated query becomes the template for everything you build after it.