Facebook Pixel
APILeads Database

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 }
    }
  }
}
ParameterRequiredDefaultNotes
valuesNofalseInline the values. Anything that is not a boolean is a 400 invalid_values, never a silent off
country_codeNo—Scopes the counts to one country. Omit for the global tally
limitNo100Per 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

KindAccepts
stringA single value. Repeat or comma-separate to OR
string_arraySame syntax; matches if any value is present on the document
booltrue / false, where only true is stored — false means "not recorded as true"
bool_exacttrue / false, both stored explicitly — false means stored false
idA 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 Internet

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

On this page