Search Profiles
Faceted search over 587 million professional profiles by country, job function, seniority, industry, technology and contact availability, with cursor pagination.
GET /leads/search
Faceted search over 587,191,569 profiles.
Result order
Results are ordered by how reachable the lead is:
| Tier | Meaning |
|---|---|
| 1 | email_verified — a verified address |
| 2 | has_email — an address, unverified |
| 3 | has_phone — a number but no address |
| 4 | none of the three |
Someone with both a verified address and a phone is in tier 1; the first key decides and the rest break ties.
The order is served straight off the index, never by sorting afterwards. That means it depends on the filter shape: a country plus a job function (optionally a seniority), or a country plus an industry. Other shapes return in index order instead, because asking for the sort there would make MongoDB order the entire match set — tens of millions of documents — before returning a page.
GET /leads/facets reports sorted on each index, so you
can tell which combinations come back ordered without guessing.
Parameters
Filters map onto the normalized facet fields. Repeat a parameter to OR — a comma also ORs, except on industry and job_function, whose own values contain one. Distinct facets AND together. See the Facets Reference for the complete table.
| Parameter | Notes |
|---|---|
country_code continent city region | city and region need an indexed companion and are never counted |
title | The person's own job title, exact. Needs a company_id in front of it — a title alone is too rare to bound a country-wide search. Does not split on comma |
job_function job_level seniority | seniority is the title ladder (c_suite, vp, owner), not job_level under another name. job_function does not split on comma |
department tenure_bucket connections_bucket | department is an array facet, never counted |
industry company_type employee_range | industry does not split on comma |
company_revenue company_followers company_founded | |
hq_country hq_state | The company's location, not the person's |
tech_categories vendors | Array facets — match if any value is present |
school degree | Free text, exact match, never counted |
email_status | Verified / Extrapolated / Unavailable |
has_email has_work_email has_phone email_verified | true / false |
company_id | The company the profile resolves to, as a 24-character hex id. Repeat to OR. The cheapest filter here, and the one a company search hands back |
domain | The employer's domain the profile carries, e.g. acme.com. Case-insensitive, and nhs.uk and www.nhs.uk are one filter |
company | The employer the profile names. Free text with no index, so it cannot lead a query — use company_id |
limit | Default 25, maximum 100 |
cursor | Opaque, from the previous response |
Example
curl -u "$LEADS_USER:$LEADS_PASS" \
"https://api.connectsafely.ai/leads/search?country_code=US&job_function=Engineering&job_level=VP&limit=25"{
"results": [
{
"linkedInUsername": "gary-althoff",
"linkedInUrl": "linkedin.com/in/gary-althoff",
"fullName": "Gary Althoff",
"firstName": "Gary",
"lastName": "Althoff",
"headline": "Global Product Development Manager",
"jobTitle": "VP Engineering and Product Development",
"jobFunction": "Engineering",
"jobLevel": "VP",
"seniority": "vp",
"emails": ["gary.althoff@kineticupstream.com"],
"emailStatus": "Verified",
"phoneNumbers": ["+1 713-438-5435"],
"companyName": "Kinetic Upstream Technologies",
"companyDomain": "kineticupstream.com",
"companyIndustry": "Oil and Gas",
"location": "houston, tx, united states",
"locationCountryCode": "US",
"linkedinConnections": 500,
"profileImage": "https://media.licdn.com/..."
}
],
"count": 25,
"hasMore": true,
"nextCursor": "MjU6MWEyYg.k3nR...",
"facets": { "job_level": [ { "value": "VP", "count": 41203 } ] },
"countsScope": "cc:US",
"countsBuiltAt": "2026-09-02T10:00:00Z"
}Pagination
Pass nextCursor back as cursor for the next page. Cursors are signed and bound to the filter that issued them:
- Altering a cursor returns
400 invalid_cursor. - Reusing a cursor with different filters returns
400 invalid_cursor, rather than silently returning pages misaligned with the new result set.
Change filters, drop the cursor. Depth is capped at 10,000 — past that, narrow the filters.
Facet counts
facets is a precomputed tally, not counts of your result set, and countsScope says what it was computed over. Both are omitted when no tally has been built. See How counts work.
Errors
| Status | Code | Cause |
|---|---|---|
| 400 | unknown_parameter | A parameter that is not a known facet — likely a typo |
| 400 | unindexed_filter | The combination would scan the collection. The message lists combinations that work |
| 400 | invalid_cursor | Altered, or issued for a different filter |
| 400 | invalid_limit | Outside 1–100 |
Not returned by search
experience and other long fields are omitted here to keep pages small. Use POST /leads/enrich for the full record on one person.
Facets Reference
Every filterable facet on the leads database - profiles and investors - with types, countability, servable filter combinations and how precomputed counts are scoped.
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.
