Facets Reference
Every filterable facet on the leads database - profiles and investors - with types, countability, servable filter combinations and how precomputed counts are scoped.
Every filter available on the leads database, what each accepts, and which combinations the API will serve. GET /leads/facets returns this same information as JSON, generated from the running build — use it when you need the live list rather than this page.
Filter syntax
The syntax is the same for every facet on both collections.
| Form | Meaning |
|---|---|
?stage=Seed | one value |
?stage=Seed&stage=Series+A | repeat a parameter — OR |
?stage=Seed,Series+A | comma-separated — OR, identical to the above, except on the facets below |
?stage=Seed§or=AI/ML | different facets — AND |
So values within one facet OR together, and distinct facets AND together. There is no syntax for NOT, and no nesting.
Four facets do not split on comma
industry and job_function on profiles, industry, company_type and specialty on
companies: their own values contain the separator. "Technology, Information and Internet" is one industry, covering 2,707,102 profiles, and splitting it asks for
three that do not exist — an empty page with no error, which is the worst way for a
filter to fail.
So on those facets the comma is part of the value, and repeating the parameter is the only way to OR:
?industry=Technology%2C%20Information%20and%20Internet one industry, whole
?industry=Legal%20Services&industry=Retail two industries, ORed
?industry=Legal Services,Retail one industry, which does not existRepeating the parameter ORs every facet, so a client that always repeats never has to
know which is which. GET /leads/facets marks these
"literal": true.
An unknown parameter is a 400, never ignored. A typo'd filter that was silently dropped would return an unfiltered slice of 587 million profiles, which looks exactly like a working query.
Profile facets
The filterable surface of the profiles collection.
Countable means the facet is eligible for the precomputed counts described below. Every profile facet is enumerable through GET /leads/facet-values — including city, which is countable: false yet fully enumerable on its own endpoint. The two flags are independent: one governs the search response, the other the values endpoint.
| Parameter | Type | Countable | Notes |
|---|---|---|---|
| Where the person is |
| Parameter | Type | Countable | Notes |
|---|---|---|---|
country_code | string | Yes | ISO-3166 alpha-2, e.g. US, GB. The most useful filter — every index but one leads with it |
continent | string | Yes | e.g. North America |
city | string | No | Filterable but never counted — unbounded cardinality. Requires an indexed companion; see City |
region | string | No | The person's state or province, e.g. ny, england. Free text with a long tail, so never counted |
Who they are
| Parameter | Type | Countable | Notes |
|---|---|---|---|
title | string | No | The person's own job title, exact match, e.g. Software Engineer. The best-covered person field there is — 99.9% of a 200,000-profile slice — and the only one seniority and job_function are derived from. Needs a company_id in front of it, not merely a country; see below. Does not split on comma |
job_function | string | Yes | e.g. Engineering, Sales |
job_level | string | Yes | The org chart, e.g. VP, Director, Staff |
seniority | string | Yes | Derived from the title, and not job_level under another name: entry, mid_level, manager, head, director, vp, c_suite, partner, owner. This is the filter for founders and decision-makers |
department | string array | Yes | e.g. engineering, information_technology. Matches if any value is present. High cardinality — the importer passes through source strings alongside its own taxonomy |
tenure_bucket | string | Yes | Time in the current role: <1y, 1-2y, 2-5y, 5-10y, 10y+ |
connections_bucket | string | Yes | Banded connection count, e.g. 1-49, 500+ |
Which company they work for
| Parameter | Type | Countable | Notes |
|---|---|---|---|
industry | string | Yes | e.g. Software Development. Does not split on comma — see above |
employee_range | string | Yes | Company headcount band, e.g. 51-200 |
company_revenue | string | Yes | Banded revenue, e.g. $1M to <$10M |
company_followers | string | Yes | Banded follower count |
company_founded | string | Yes | Banded founding year |
company_type | string | Yes | Privately Held, Public Company, Nonprofit, Government Agency, Educational, Partnership, Self-Owned, Self-Employed. The filter that keeps sole traders out of a B2B list |
hq_country | string | Yes | The company's country, which is a different question from the person's: "engineers anywhere, at US-headquartered companies" |
hq_state | string | No | The company's state or province. Free text with a long tail, so never counted |
tech_categories | string array | Yes | Broad technology categories in use, e.g. infrastructure_hosting, analytics. Matches if any value is present |
vendors | string array | Yes | The named products the company was detected using, e.g. cloudflare, microsoft365, google-tag-manager. Matches if any value is present. GET /leads/vendors lists the slugs and how many companies carry each |
company | string | No | The employer the profile names. Exact match, case-insensitive. Free text with no index behind it, so it cannot lead a query — use company_id |
company_id | id | No | The company this profile resolves to, as a 24-character hex id. The cheapest filter on the collection and the only company filter with an index of its own. Several ids OR. This is how a company filter reaches people: narrow companies, then pass their ids |
domain | string | No | The employer's domain as the profile carries it, e.g. acme.com. On 90.4% of a 200,000-profile slice — the direct answer to "the people at acme.com", with no company lookup first. Matched case-insensitively and in both spellings, so nhs.uk and www.nhs.uk are one filter; see below. One caveat left to you: the head of the distribution is link shorteners rather than employers (linktr.ee, bit.ly), which is why it is never counted. Needs a country and a job function in front of it, or a company_id |
Education
| Parameter | Type | Countable | Notes |
|---|---|---|---|
school | string | No | Free text from the source profile, including non-Latin spellings. Exact match only; never counted, because a rollup would be a thousand near-duplicate spellings of one university |
degree | string | No | Same, e.g. bachelor, master's degree |
Reachability
| Parameter | Type | Countable | Notes |
|---|---|---|---|
email_status | string | Yes | The provider's own verdict: Verified, Extrapolated, Unavailable. Distinct from the two booleans below — has_email says an address exists, email_verified says it was confirmed, this says which of the three states was reported |
has_email | bool | Yes | true / false |
has_work_email | bool | Yes | true / false |
has_phone | bool | Yes | true / false |
email_verified | bool | Yes | true / false |
Facet coverage
A filter can only match profiles that carry the facet, and coverage varies a lot. A narrow result set for a sparse facet is coverage, not a bug — so check this table before concluding a filter is broken.
These are exact, not sampled: each figure is the facet's own count across all 587,191,569 profiles.
| Facet | Profiles carrying it | |
|---|---|---|
country_code | 527,333,337 | 89.8% |
continent | 525,926,686 | 89.6% |
connections_bucket | 289,926,738 | 49.4% |
job_level | 287,059,974 | 48.9% |
industry | 281,429,721 | 47.9% |
employee_range | 272,418,322 | 46.4% |
company_followers | 268,818,408 | 45.8% |
job_function | 265,382,851 | 45.2% |
company_revenue | 262,597,271 | 44.7% |
company_type | 247,510,045 | 42.2% |
hq_country | 228,386,395 | 38.9% |
has_email | 193,890,070 | 33.0% |
company_founded | 175,848,953 | 29.9% |
tenure_bucket | 164,223,043 | 28.0% |
has_work_email | 146,058,501 | 24.9% |
email_status | 83,998,886 | 14.3% |
seniority | 77,159,768 | 13.1% |
has_phone | 41,280,008 | 7.0% |
email_verified | 26,104,744 | 4.4% |
seniority, email_status, has_phone and email_verified are the sparse ones.
Filtering on seniority restricts you to 13.1% of the database before any other
filter applies, and email_verified to 4.4%. They are precise filters, not broad ones
— combine them with a wide facet like country_code, and expect small result sets.
The array facets — vendors, tech_categories, department — are not in the table
because a profile can carry several values, so their totals count pairs rather than
profiles. For scale: vendors holds 1,468 distinct slugs over 620,093,221
profile-vendor pairs, led by google-tag-manager at 49,000,667 profiles.
city, region, hq_state, school and degree are not in the table either: they are
deliberately never tallied (see below), so no exact figure exists for
them. They sit roughly between 55% and 85%.
Booleans on profiles are "known true", not "stored false"
The four profile booleans are only ever written when true. has_email=false therefore means "not recorded as having an email" — which includes profiles nobody has checked. It does not mean "confirmed to have none".
This also has a performance consequence: has_*=false compiles to a "not true" test, which cannot seek an index. It is applied after an indexed facet has narrowed the candidates, so a false filter must always accompany one that can be indexed.
Investor booleans behave differently — see below.
Servable filter combinations
Profile search rejects any filter that would scan the collection, with 400 unindexed_filter. At 587 million documents an unplanned query is not slow, it is unavailable, and failing in milliseconds beats timing out.
Four indexes exist:
| Index | Keys, in order |
|---|---|
f_country_func_level | country_code → job_function → job_level |
f_country_industry | country_code → industry |
f_func_conn | job_function → connections_bucket |
p_companyId | company_id |
A query is servable when its filters include a leading prefix of one of these.
company_id leads a search on its own, and it is the cheapest filter on the
collection — 7ms for "everyone at this company", against a 400 or a timeout for the
free-text company. It is also how a company filter reaches people: narrow
companies on GET /leads/companies, then pass the ids
back here. Several ids OR, and the number is not capped — measured on the live
collection, 1,000 ids answer in 55ms.
| Query | Result |
|---|---|
?country_code=US | Served — prefix of two indexes |
?company_id=6a503c12cb31b2061602783a | Served — a full index of its own |
?country_code=US&job_function=Engineering | Served |
?country_code=US&job_function=Engineering&job_level=VP | Served — full index |
?country_code=US&industry=Software | Served |
?job_function=Sales&connections_bucket=1-49 | Served |
?country_code=US&city=houston&has_email=true | Served — country leads, the rest post-filter |
?city=houston | 400 — no index leads with city |
?has_email=true | 400 — no index leads with a boolean |
?job_level=VP | 400 — job_level is third in its index, not a prefix |
The error names the combinations that would work, so a client can recover without consulting this page.
In practice: lead with country_code, or with job_function. Everything else narrows from there.
A title needs a company in front of it
title and domain are post-filters — nothing indexes jobTitle or companyDomain —
so each one rides whatever prefix led the query, and how wide that prefix is decides
whether the request comes back. Measured against the live collection on 11 Oct 2026, ten
rows wanted against the 15 second budget:
| lead | title | domain |
|---|---|---|
company_id | 89ms | 179ms |
country_code + job_function | 504 | 643ms |
country_code alone | 504 | 504 |
A rare title inside the US index range has to be read past until ten matches turn up, and
for most titles they never do — the same shape that makes department unusable on a bare
country. So:
# Right: the company bounds it. 89ms.
GET /leads/search?company_id=6ab4cd08a90da71a167faaf7&title=Software%20Engineer
# Wrong: 504, even with a job function. Nothing bounds the title.
GET /leads/search?country_code=US&job_function=Engineering&title=Software%20EngineerGet the id from GET /leads/companies first. domain
is the looser of the two and survives a country plus a function.
Note title does not split on comma: 7,881 of 102,586 distinct titles contain one
(4.0% of profiles), so Environment, Health and Safety Manager is a single title.
domain matches both spellings
The writer never normalised companyDomain: it stores whatever the source gave it, so
one employer can be filed under either nhs.uk or www.nhs.uk.
Measured over 270,877 profiles, 32 values carry a www. prefix — 890 profiles, 0.33% —
and exactly one of them also has its bare form stored. That last number is the
problem. For the other 31 the bare form is not stored at all, so an exact filter on the
obvious spelling returned zero rather than a short page:
?domain=nhs.uk 0 rows before
?domain=www.nhs.uk 325 rowsSo a supplied domain is lower-cased, has any www. stripped, and is matched against both
spellings. nhs.uk, www.nhs.uk and NHS.UK are one filter with one cursor
fingerprint. Hosts are case-insensitive by definition, and 18 of 97,208 stored values
carry an uppercase letter.
City
city is the one facet with no index and no counts. It is free text from four importers, so values vary in spelling and form — new york city, greater london.
Two consequences:
- It must accompany an indexed facet.
?city=houstonalone is a400;?country_code=US&city=houstonis fine. - You cannot discover values from the count block.
GET /leads/facet-valuesexists for exactly this — passfacet=city&country_code=USfor the cities known in a country, most populous first, with substring search for type-ahead. City is the one facet wherecountry_codeis required, since it has no global tally.
How counts work
A search response may carry a facets block. These are precomputed counts, not counts of your result set.
{
"results": [ /* ... */ ],
"facets": { "job_level": [ { "value": "VP", "count": 41203 } ] },
"countsScope": "cc:US",
"countsBuiltAt": "2026-09-02T10:00:00Z"
}countsScope tells you what the numbers were computed over:
| Scope | Meaning |
|---|---|
cc:US | Counted across that one country — returned when your query pins exactly one country_code |
global | Counted across the whole collection |
Counting live over 587 million documents would scan the collection on every request. Instead one offline pass tallies every countable facet and the server holds the result in memory, so a count costs a map lookup.
Counts for arbitrary filter combinations do not exist. They would be a data cube. If you filter by country_code=US&job_function=Engineering, the returned job_level counts are for the whole of US — not for engineers in the US. countsScope is what stops that being read as more than it is.
city is deliberately absent from this block regardless of scope.
The block is omitted entirely when no tally has been built. Search still works; it simply returns no facets and no countsScope. GET /leads/health reports rollupRows: 0 in that state.
Company facets
The filterable surface of the companies_v2 collection, 22.3 million documents. These
are accepted by GET /leads/companies and
GET /leads/vendors/{slug}/companies.
| Parameter | Type | Countable | Notes |
|---|---|---|---|
industry | string | Yes | The company's own industry, e.g. Software Development. Does not split on comma |
company_type | string | Yes | Privately Held, Public Company, Nonprofit, Government Agency, Educational. Does not split on comma |
revenue | string | Yes | Banded, e.g. $10M to <$50M |
vendors | string array | Yes | Vendor slug, the same vocabulary GET /leads/vendors lists |
tech_categories | string array | Yes | Broad technology categories, e.g. cdn, analytics |
specialty | string array | No | Free text from the company page. 336,962 distinct values, so filterable on an exact match and never counted. Does not split on comma |
A company facet narrows a search; it never leads one
companies_v2 has two indexes a search can lead with: the collated name prefix, and the
vendor slug. Every facet above is a post-filter on whichever of those already bounded
the candidate set.
So a company facet always accompanies a q= prefix or a vendor slug, and a facet-only
company search is refused rather than run:
# Served: the prefix leads, the facets narrow.
GET /leads/companies?q=marri&industry=Hospitality&company_type=Public%20Company
# Served: the slug leads.
GET /leads/vendors/cloudflare/companies?company_type=Nonprofit
# 400: nothing bounds it, and scanning 22.3M documents is not a search.
GET /leads/companies?industry=HospitalityOn the vendor endpoint the slug in the path is the vendors filter, so passing
?vendors= as well is a 400 rather than a second, possibly contradictory filter.
Why these are not profile facets
Several of these names also appear on the profile surface, where they read a copy of the
company's data flattened onto the person. That copy is going away: a profile will carry
companyId and nothing else about its employer.
The route from a company filter to people is therefore two calls, not one — narrow
companies here, then pass the ids you get back to
GET /leads/search?company_id=…&company_id=…. That filter has its own index, several
ids OR, and the count is uncapped: 1,000 ids answer in 55ms on the live collection.
Two fields that are deliberately not facets
companySize is not offered. Every useful band contains the separator —
1,001-5,000, 501-1,000, 10,001+ — and the bands are opaque strings while the
number behind them is not: GET /leads/vendors/{slug}/companies filters it directly as
min_employees.
hqCountry is not offered either. It holds free-text country names in inconsistent
case — united states on 24,813 companies and United States on 3,508 — while the
hq_country profile facet of the same name holds two-letter codes. One parameter with
two vocabularies is worse than no parameter.
Investor facets
The investors collection is five orders of magnitude smaller, so it gets different affordances.
Investor facets are not served by /leads/facet-values — that endpoint reads the profiles rollup. Investor counts are computed live and filter-aware by GET /leads/investors; call it with limit=1 and read its facets block. GET /leads/facets reports values: false on them for this reason.
| Parameter | Type | Countable | Notes |
|---|---|---|---|
investor_type | string array | Yes | e.g. Venture Capital, VC, Private Equity, Private Investment Firm, Angel |
stage | string array | Yes | e.g. Seed, Series A, Growth, Buyout, Pre-IPO |
sector | string array | Yes | e.g. Technology, Healthcare, Real Estate |
geo_focus | string array | Yes | Countries the investor targets |
has_email | bool | Yes | Whether the investor has a stored email address |
has_linkedin | bool | Yes | Whether the investor has a stored LinkedIn URL |
The investor vocabulary is the source's own
Investor facet values are not a normalized closed vocabulary. The collection merges
several sources and keeps their words, so investor_type holds both Venture Capital
and VC, and both Angel and Angel Investor; stage holds private-equity stages
(Buyout, Turnaround, Distressed, Pre-IPO) alongside venture ones.
Build your filter list from the counts in the response rather than from a hardcoded list. Investor counts are live and filter-aware, so every value they report is a value that returns rows — which is what makes the raw vocabulary workable. A hardcoded list will split a filter in half.
Coverage is thin on contact details. Of 54,954 investors, 27,791 carry a LinkedIn
URL and only 2,825 — 5.1% — carry an email address. has_email=true is a small
slice of the database, not a minor filter.
Filters this collection does not support
Five facets that earlier versions of this API advertised are not available, because nothing in the stored documents supports them without inventing a value:
| Facet | Why |
|---|---|
kind (firm / person) | Not stored. People are folded into a firm's team rather than being separate records, so the distinction no longer describes the data. The only signal is the LinkedIn URL shape, and it covers about half the collection |
country_code, city | location is one free-text string ("Île-de-France, France") with no separate country or city |
check_size | Stored as {min, max, label} numbers with a free-text label, not one of seven bands. Filter on the numbers if you need a range |
leads_rounds | No source field |
Sending any of them is a 400 unknown_parameter, which is deliberate: a filter that
silently matched nothing would return an unfiltered slice of the collection and look
like a working query.
No index planning
Investors declare no indexes and no filter combination is ever rejected. A full scan of 55k documents is milliseconds, so forcing index hints would add a failure mode to buy nothing.
Profiles and investors compared
(Companies sit between the two: no index planning to satisfy, like investors, but no facet that can lead a query either — see above.)
Both emit facet counts in the same shape, but they mean different things.
/leads/search (587M) | /leads/investors (55K) | |
|---|---|---|
| Facet counts | Precomputed, global or cc:XX scope | Live and filter-aware |
| Facet vocabulary | Normalized by the importer | The sources' own words — read it off the counts |
total | Omitted — counting is unaffordable | Real total and page count |
| Pagination | Signed cursor, depth capped at 10,000 | Page numbers |
| Text search | Not supported | q across name, firm and description |
| Index planning | Mandatory; unservable filters are 400 | None needed |
Data coverage
The facet fields are written by a separate backfill process and only read by this API. Coverage is partial — many profiles carry no classification at all, so a filter can legitimately return zero results even where a large population exists.
Two consequences worth designing around:
- A facet filter returning nothing does not mean nobody matches — it may mean the population is not yet classified.
- The precomputed counts are the reliable way to see which values actually carry data. Where no tally has been built, there is no way to tell a genuinely empty facet from an unclassified one.
Build a UI against GET /leads/facets for the parameter list and GET /leads/facet-values for the values of any given facet, rather than hard-coding value lists that may not match the data.
Leads Database API
Search a database of 587 million professional profiles and 55 thousand investors by country, job function, seniority, industry, technology and contact availability.
Search Profiles
Faceted search over 587 million professional profiles by country, job function, seniority, industry, technology and contact availability, with cursor pagination.
