Documentation
Find people and companies by ICP rather than one at a time. 996M people, 73M companies, with cursor paging, a stable response envelope, and a free company count with breakdowns for sizing a market before you buy a single record.
/v1/people/search and /v1/companies/search answer from an index of 996,165,074 people and 73,728,117 companies. Page with meta.nextCursor; one record is counted per person returned. A 503 from these endpoints now means the index is temporarily unreachable rather than absent — retry with backoff.Person enrichment and company lookup answer today, from our own store.
GET /v1/people/search · 1 record per person returned · scope search
Also accepted as POST with a JSON body, which is easier once you have more than a handful of filters. Combine any of the people filters; they join with AND, while several values inside one filter join with OR.
| Field | Type | Meaning |
|---|---|---|
| (filters) | see the filter reference | Any people filter. Arrays are comma-separated in a query string, JSON arrays in a POST body. |
| limit | integer · 1–100 · default 25 | People per page. Each person returned counts one record. |
| count | boolean · default false | Also return meta.total, exact. With limit=1 this is a free sizing call: no rows, no records spent, meta.countOnly: true. A counted search also carries meta.distinctCompanies — how many employers the matched people span (exact below 40,000; distinctCompaniesIsExact says). |
| facets | boolean · default false | Break the matched set down by seniority, country, industry and company size, free with count. Add facetCompanies=true for a companies figure inside each bucket (an estimate; for narrow audiences — on a very broad one the per-bucket figures are dropped and meta.facetCompaniesWithheld says so). |
| slim | boolean · default false | Drop empty fields, the picture block and duplicate lists from each record. MCP clients get this by default. |
| fields | string[] | Keep only these dotted paths, e.g. profile_data.profile_full_name,meta.source_ids. Applied after slim. |
| cursor | string | meta.nextCursor from the previous page, passed back exactly as it was handed to you. |
Results are thin person records — identity, headline, current role and company, location, and the has_email / email_status / email_type flags. That is enough to decide who is worth pursuing. Contact points come from enrichment, which is a separate call on the people you actually chose.
Keyword filters such as title and companyName match a phrase — ["auto parts"] needs both words, adjacent. Wrap a value in [brackets] for an exact match: ["[Advance Auto Parts]"] matches that company name and nothing else, case-insensitive.
email_type says what kind the person’s best address is, and the emailType filter takes the same values — so emailStatus=verified&emailType=work asks for a deliverable address at the company they work for now. Without it a B2B list quietly includes people whose only good address is webmail, or worse is at an employer they left: that is work_other, and it is a separate value precisely so you never get it by asking for work. Use work_any when you want both.
GET /v1/companies/search · 1 record per company returned · scope search
The same idea, company-side: industry, headcount, revenue, funding, technologies and headquarters. Also accepted as POST. Records come back in the leadocean.company.v1 shape.
| Field | Type | Meaning |
|---|---|---|
| (filters) | see the filter reference | Any company filter — industry, headcount, revenue, funding, technologies, headquarters. |
| limit | integer · 1–100 · default 25 | Companies per page. Each company returned counts one record. |
| count | boolean · default false | With limit=1 it is free. You rarely need it: the first page of a company search is always counted and meta.total travels in the cursor, so every page carries the exact total without recounting. |
| slim | boolean · default false | Drop the technology list (the count stays), tags, specialties, financials and every empty field — about a third of the full size. MCP clients get this by default. |
| fields | string[] | Keep only these dotted paths, e.g. company_data.company_name,company_data.company_domain,meta.source_ids. |
| cursor | string | meta.nextCursor from the previous page, passed back exactly as it was handed to you. |
Company name follows the same phrase-or-[exact] rule as people’s companyName.
GET /v1/companies/count · free · scope search · MCP leadocean_count_companies
How many companies match a filter set, exactly, broken down by industry, headcount band, HQ country, HQ state and primary NAICS code — the top 20 of each. It takes the company-search filters, returns no rows and spends no records. This is the TAM call: size the market, read the breakdowns, then search or export the slice you want.
| Field | Type | Meaning |
|---|---|---|
| (filters) | see the filter reference | Exactly the company-search filters. No paging fields. |
| hasMailableContacts | boolean | true = companies with at least one person whose best email is verified, catch_all_valid or catch_all; false = companies with none. |
| naicsPrimary | string[] | The one NAICS code a company is filed under (company_data.naics_primary); naics matches any listed code. |
| naicsSector | enum[] | Two-digit NAICS sector, 21 values — the coarse cut for sizing. On companies it is the derived sector the record shows. |
Response: { total, totalIsExact, facets: { industry, employee_range, hq_country, hq_state, naics_primary } }, each facet a list of { value, count }. No email-status default applies — this counts companies, not mailable people; hasMailableContacts=true is how you ask for the ones you can write to. A filter the index cannot answer is named in meta.unsupportedFilters and the total is withheld (null with totalWithheld) rather than published wrong.
For people, the equivalent is count=true&limit=1 on the people search: free, with meta.total and meta.distinctCompanies, how many employers those people span. Over MCP, leadocean_count_leads also returns totalAll — the same filters with no email condition — so the mailable default never hides the size of the whole audience.
Page with meta.nextCursor: pass it back as cursor on the next request. A page with no nextCursor is the last one, and a cursor is tied to one filter set — change a filter and you start a new search rather than resuming the old one.
A cursor is opaque and signed. Pass back exactly the string we gave you. There is nothing inside it to read, and one that has been edited, truncated or built by hand is a 400 Invalid cursor rather than a page from somewhere else in the results. Treat it as good for the walk you are in the middle of and not as something to keep: cursors issued before 19 September 2026 are no longer valid, so a caller still holding one starts again at page one.
Paging also stops at a fixed depth — 10,000 rows per search by default. The page that reaches it carries meta.depthCapped: true and no further cursor. That is rows walked, not records bought; records, limits and errors spells out the difference.
| meta field | Meaning |
|---|---|
| nextCursor | Opaque cursor for the next page, or absent on the last page. |
| depthCapped | true on the page that reaches the depth limit, and absent otherwise. No further cursor is issued — narrow the filters and search again. |
| total | Exact size of the matched set. On the people search it is present when you ask with count=true; on the company search it is always present (counted once, on the first page, and carried in the cursor). Null, with totalWithheld, when a requested filter could not be applied. |
| distinctCompanies | People search with count or facets: how many distinct employers the matched people span. distinctCompaniesIsExact is true below 40,000 and false for a close estimate above. |
| unsupportedFilters | Names any filter the answering dataset ignored, so a query never silently returns more than you asked for. |
| notice | Present when something about the answer needs explaining — being paced past your records, for one. |
A search page is trimmed to whatever records you have left rather than overshooting them — see records, limits and errors. Every filter, with its type and allowed values, is on the filter reference.