Describe Facets
Return every filterable parameter on the leads database with its type, countability and the servable index combinations, as JSON.
GET /leads/facets
Every filterable parameter on all three collections, its type, whether it can be counted, and which filter combinations profile search will serve.
Reads compiled definitions — it touches neither the database nor the precomputed tally, so it answers on a fresh deployment before anything else is ready.
Without it a client discovers valid parameters by trying them and collecting 400s.
Example
curl -u "$LEADS_USER:$LEADS_PASS" https://api.connectsafely.ai/leads/facets{
"profiles": {
"facets": [
{ "param": "country_code", "kind": "string", "countable": true, "values": true },
{ "param": "city", "kind": "string", "countable": false, "values": true },
{ "param": "tech_categories", "kind": "string_array", "countable": true, "values": true },
{ "param": "industry", "kind": "string", "countable": true, "values": true, "literal": true },
{ "param": "has_email", "kind": "bool", "countable": true, "values": true },
{ "param": "company_id", "kind": "id", "countable": false, "values": true }
],
"indexes": [
{ "name": "f_country_func_level", "keys": ["country_code", "job_function", "job_level"] },
{ "name": "f_country_industry", "keys": ["country_code", "industry"] },
{ "name": "f_func_conn", "keys": ["job_function", "connections_bucket"] },
{ "name": "p_companyId", "keys": ["company_id"] }
]
},
"companies": {
"facets": [
{ "param": "industry", "kind": "string", "countable": true, "values": false, "literal": true },
{ "param": "company_type", "kind": "string", "countable": true, "values": false, "literal": true },
{ "param": "revenue", "kind": "string", "countable": true, "values": false },
{ "param": "vendors", "kind": "string_array", "countable": true, "values": false },
{ "param": "tech_categories", "kind": "string_array", "countable": true, "values": false },
{ "param": "specialty", "kind": "string_array", "countable": false, "values": false, "literal": true }
],
"indexes": []
},
"investors": {
"facets": [
{ "param": "investor_type","kind": "string_array", "countable": true, "values": false },
{ "param": "stage", "kind": "string_array", "countable": true, "values": false },
{ "param": "has_email", "kind": "bool", "countable": true, "values": false }
],
"indexes": []
}
}One call for a whole filter UI
?values=true inlines the values of every profile facet alongside the definitions, so a
filter sidebar fills all twenty-nine dropdowns in one request rather than one per facet.
curl -u "$LEADS_USER:$LEADS_PASS" \
"https://api.connectsafely.ai/leads/facets?values=true&country_code=US"{
"profiles": { "facets": [ /* ... */ ], "indexes": [ /* ... */ ] },
"companies": { "facets": [ /* ... */ ], "indexes": [] },
"investors": { "facets": [ /* ... */ ], "indexes": [] },
"values": {
"scope": "cc:US",
"builtAt": "2026-09-02T10:00:00Z",
"limit": 100,
"facets": {
"job_level": {
"results": [ { "value": "Director", "count": 88110 }, { "value": "VP", "count": 41203 } ],
"total": 2
},
"city": { "results": [ { "value": "new york city", "count": 812441 } ], "total": 1000 }
}
}
}| Parameter | Required | Default | Notes |
|---|---|---|---|
values | No | false | Inline the values. Anything that is not a boolean is a 400 invalid_values, never a silent off |
country_code | No | — | Scopes the counts to one country. Omit for the global tally |
limit | No | 100 | Per facet. Maximum 500 |
Each entry carries results and the pre-limit total, so a truncated long tail
(tech_categories, city) is visible and can be paged through
GET /leads/facet-values, which reads the same tally
through the same code — the two cannot drift.
city is inlined only when country_code is given. It is tallied per country, and
an empty list would read as "this country has no cities"; the key is absent instead. A
city filter needs a country to be servable anyway.
Investor facets are not in the bundle. Their counts are live and filter-aware,
computed by GET /leads/investors; a frozen copy here
would be a second, staler answer to the same question.
Without a built tally the bundle is present but every facet is empty, and builtAt is
absent — a 200, not an error. GET /leads/health reports rollupRows: 0 in that
state. Plain GET /leads/facets still answers in full, so parameter names remain
discoverable on a fresh deployment.
Kinds
| Kind | Accepts |
|---|---|
string | A single value. Repeat or comma-separate to OR |
string_array | Same syntax; matches if any value is present on the document |
bool | true / false, where only true is stored — false means "not recorded as true" |
bool_exact | true / false, both stored explicitly — false means stored false |
id | A 24-character hex id, as a company endpoint returned it. Repeat or comma-separate to OR |
literal: true — do not comma-separate this one
Comma is the OR separator, which silently breaks any facet whose own values contain one.
industry is the case that matters: 330 of its 5,822 profile values carry a comma,
covering 9,037,733 profiles, and "Technology, Information and Internet" alone is
2,707,102 of them.
A facet marked literal: true therefore does not split on comma — the whole string
is one value:
# Right: the value, whole.
?industry=Technology%2C%20Information%20and%20Internet
# Right: two industries, ORed by repeating the parameter.
?industry=Legal%20Services&industry=Retail
# Wrong: three industries that do not exist. An empty page, with no error.
?industry=Technology,Information and InternetRepeating the parameter ORs every facet, literal or not, so a client that always
repeats never has to read this flag. The flag is absent (rather than false) on facets
that still split.
Reading indexes
For profiles, a query is servable when its filters include a leading prefix of one listed index. country_code alone works; job_level alone does not, because it is third in its index.
"indexes": [] is not an omission on either of the other two surfaces, but it means
different things.
Investors declare none because the collection is small enough that any filter combination is servable.
Companies declare none because no company facet can lead a search. Every one of
them is a post-filter on something that already bounded the scan — a name prefix on
GET /leads/companies or the slug on
GET /leads/vendors/{slug}/companies. A facet-only company search is refused, not run.
To go from a company filter to people, narrow companies first and pass the ids you get
back to GET /leads/search?company_id=….
Countability
countable: false means the facet can be filtered on but never appears in the facets count block on a search response. It is the mark of an unbounded or free-text vocabulary: city, region, hq_state, school, degree, department and company on profiles, specialty on companies, and company_id, which is an identifier rather than a value anyone browses.
values: true means GET /leads/facet-values can enumerate the facet — true for every profile facet, city included, since the rollup tallies them all. Company and investor facets report values: false, for different reasons: investor counts are computed live by GET /leads/investors, and companies are not rolled up at all.
Note that countable and values are independent. city is countable: false but values: true — it is excluded from search responses yet fully enumerable on its own endpoint.
See the Facets Reference for the complete table with descriptions.
List Facet Values
List the known values for any filterable facet on the leads database, most common first, with counts and substring search for building filter dropdowns.
Vendors and Technologies
List the technologies detected across 22 million companies, find the companies running one, and filter people by their employer's stack.
