Facebook Pixel
APILeads Database

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.

FormMeaning
?stage=Seedone value
?stage=Seed&stage=Series+Arepeat a parameter — OR
?stage=Seed,Series+Acomma-separated — OR, identical to the above, except on the facets below
?stage=Seed&sector=AI/MLdifferent 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 exist

Repeating 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.

ParameterTypeCountableNotes
Where the person is
ParameterTypeCountableNotes
country_codestringYesISO-3166 alpha-2, e.g. US, GB. The most useful filter — every index but one leads with it
continentstringYese.g. North America
citystringNoFilterable but never counted — unbounded cardinality. Requires an indexed companion; see City
regionstringNoThe person's state or province, e.g. ny, england. Free text with a long tail, so never counted

Who they are

ParameterTypeCountableNotes
titlestringNoThe 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_functionstringYese.g. Engineering, Sales
job_levelstringYesThe org chart, e.g. VP, Director, Staff
senioritystringYesDerived 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
departmentstring arrayYese.g. engineering, information_technology. Matches if any value is present. High cardinality — the importer passes through source strings alongside its own taxonomy
tenure_bucketstringYesTime in the current role: <1y, 1-2y, 2-5y, 5-10y, 10y+
connections_bucketstringYesBanded connection count, e.g. 1-49, 500+

Which company they work for

ParameterTypeCountableNotes
industrystringYese.g. Software Development. Does not split on comma — see above
employee_rangestringYesCompany headcount band, e.g. 51-200
company_revenuestringYesBanded revenue, e.g. $1M to <$10M
company_followersstringYesBanded follower count
company_foundedstringYesBanded founding year
company_typestringYesPrivately Held, Public Company, Nonprofit, Government Agency, Educational, Partnership, Self-Owned, Self-Employed. The filter that keeps sole traders out of a B2B list
hq_countrystringYesThe company's country, which is a different question from the person's: "engineers anywhere, at US-headquartered companies"
hq_statestringNoThe company's state or province. Free text with a long tail, so never counted
tech_categoriesstring arrayYesBroad technology categories in use, e.g. infrastructure_hosting, analytics. Matches if any value is present
vendorsstring arrayYesThe 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
companystringNoThe 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_ididNoThe 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
domainstringNoThe 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

ParameterTypeCountableNotes
schoolstringNoFree 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
degreestringNoSame, e.g. bachelor, master's degree

Reachability

ParameterTypeCountableNotes
email_statusstringYesThe 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_emailboolYestrue / false
has_work_emailboolYestrue / false
has_phoneboolYestrue / false
email_verifiedboolYestrue / 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.

FacetProfiles carrying it
country_code527,333,33789.8%
continent525,926,68689.6%
connections_bucket289,926,73849.4%
job_level287,059,97448.9%
industry281,429,72147.9%
employee_range272,418,32246.4%
company_followers268,818,40845.8%
job_function265,382,85145.2%
company_revenue262,597,27144.7%
company_type247,510,04542.2%
hq_country228,386,39538.9%
has_email193,890,07033.0%
company_founded175,848,95329.9%
tenure_bucket164,223,04328.0%
has_work_email146,058,50124.9%
email_status83,998,88614.3%
seniority77,159,76813.1%
has_phone41,280,0087.0%
email_verified26,104,7444.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:

IndexKeys, in order
f_country_func_levelcountry_code → job_function → job_level
f_country_industrycountry_code → industry
f_func_connjob_function → connections_bucket
p_companyIdcompany_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.

QueryResult
?country_code=USServed — prefix of two indexes
?company_id=6a503c12cb31b2061602783aServed — a full index of its own
?country_code=US&job_function=EngineeringServed
?country_code=US&job_function=Engineering&job_level=VPServed — full index
?country_code=US&industry=SoftwareServed
?job_function=Sales&connections_bucket=1-49Served
?country_code=US&city=houston&has_email=trueServed — country leads, the rest post-filter
?city=houston400 — no index leads with city
?has_email=true400 — no index leads with a boolean
?job_level=VP400 — 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:

leadtitledomain
company_id89ms179ms
country_code + job_function504643ms
country_code alone504504

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%20Engineer

Get 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 rows

So 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=houston alone is a 400; ?country_code=US&city=houston is fine.
  • You cannot discover values from the count block. GET /leads/facet-values exists for exactly this — pass facet=city&country_code=US for the cities known in a country, most populous first, with substring search for type-ahead. City is the one facet where country_code is 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:

ScopeMeaning
cc:USCounted across that one country — returned when your query pins exactly one country_code
globalCounted 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.

ParameterTypeCountableNotes
industrystringYesThe company's own industry, e.g. Software Development. Does not split on comma
company_typestringYesPrivately Held, Public Company, Nonprofit, Government Agency, Educational. Does not split on comma
revenuestringYesBanded, e.g. $10M to <$50M
vendorsstring arrayYesVendor slug, the same vocabulary GET /leads/vendors lists
tech_categoriesstring arrayYesBroad technology categories, e.g. cdn, analytics
specialtystring arrayNoFree 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=Hospitality

On 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.

ParameterTypeCountableNotes
investor_typestring arrayYese.g. Venture Capital, VC, Private Equity, Private Investment Firm, Angel
stagestring arrayYese.g. Seed, Series A, Growth, Buyout, Pre-IPO
sectorstring arrayYese.g. Technology, Healthcare, Real Estate
geo_focusstring arrayYesCountries the investor targets
has_emailboolYesWhether the investor has a stored email address
has_linkedinboolYesWhether 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:

FacetWhy
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, citylocation is one free-text string ("Île-de-France, France") with no separate country or city
check_sizeStored 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_roundsNo 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 countsPrecomputed, global or cc:XX scopeLive and filter-aware
Facet vocabularyNormalized by the importerThe sources' own words — read it off the counts
totalOmitted — counting is unaffordableReal total and page count
PaginationSigned cursor, depth capped at 10,000Page numbers
Text searchNot supportedq across name, firm and description
Index planningMandatory; unservable filters are 400None 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.

On this page