Company Search
/v2/companies/searchSearch our company database by identity, company attributes and free-text keywords. Look up specific companies by name, domain or LinkedIn id, or build a target list by industry, location (city, state, country or region), headcount, founded year, company type, business type, revenue stream and NAICS codes: filters AND together, and at least one include condition is required. Results return 25 per page by default (per_page: 25, 50 or 100), sorted by relevance when keywords are present and by followers otherwise - see the body parameters below for every filter and its nuances. Free: spends no credits; 1 unit of the search rate limit per 25 results. Authenticate with your API key in the x-api-key header.
How are credits spent?
Company Search is free. Searching and paging through results never charges credits - credits are only spent when you enrich people or reveal contact data on other endpoints.
How filtering works
Send one filters object. Every filter is optional, but at least one
include condition is required (exclude-only searches are rejected), and a
request can carry at most 20,000 filter values in total. Most filters share
the same shape - an include list ("match any of these") and an exclude
list ("reject these") - and all active filters combine with AND:
- Identity filters (
company.id,company.name,company.domain,company.linkedin_id) look up specific companies you already know - the same keys as People Search'scompanyfilter. - Company attribute filters describe the kind of company:
company_industry,company_country(any office location by default,headquarters_onlyto restrict), headcount (company_headcount_rangebuckets orcompany_headcount_customraw numbers),company_founded,company_type,company_business_type,company_revenue_stream, andcompany_naics. company_keywordsmatches free-text phrases across the company's profile; narrow it withsourcesandinclude_all.
Enum-backed filters only accept values from Enums; each parameter below links to its own value list.
Companies you already know
company.id takes our own company id - the value on every result here and on
every Company Enrich response. It is the exact way
to name companies you have already resolved, and the one identifier that can
never be ambiguous: a name or a domain can be shared by several companies,
while an id names exactly one.
So when you start from something like a company website or LinkedIn URL, the reliable path is two steps - enrich first, keep the ids, then filter by them:
- Call Company Enrich with the
domain,name,linkedin_urlorlinkedin_idyou hold, and readidoff the response. - Send those ids here as
company.id.include(up to 20,000 per request - the request-wide filter-value cap), or to People Search'scompany.idfilter, which takes the same value.
company.id.exclude rejects companies the same way, and - like every other
exclude - it needs at least one include filter beside it.
This two-step is also the answer for LinkedIn: company.linkedin_id takes
LinkedIn's numeric company id, never a linkedin.com/company/... URL.
Enrich the URL into an id and filter on that.
Finding the people who work there
Each result carries an id. Pass those ids to
People Search's company.id filter to list the
people working at the companies you found - the classic two-step for
building an account-based prospect list.
Sorting and pagination
Results come back 25 per page by default; set per_page to 50 or 100 for
bigger pages. A search reaches 25,000 results at any page size: page 1000 at
25, page 250 at 100.
The default order is relevance when company_keywords is present and
follower count otherwise; override it with sort_by and sort_direction.
The response metadata echoes the sort_by / sort_direction that
actually ran, so you can confirm which default kicked in. See
Pagination for the response envelope and paging
patterns.
Body parameters
filtersobjectrequiredFilter configuration. Active filters AND together and at least one include condition is required (exclude-only searches are rejected). A request can carry at most 20,000 filter values in total. See Enums for allowed values per enum filter.
Child attributes
companyobjectoptionalLook up specific companies you already know - by our own
id(the exact one, as returned by Company Enrich), by exactname, by webdomain, or by numericlinkedin_id. The same keys as People Search'scompanyfilter.Child attributes
idobjectoptionalMatch by our company
id, as returned by this endpoint and by Company Enrich. The exact way to name companies you have already resolved.Field Type Description includestring[] Only these companies, by id. Max 20000 ids.Example:
["64f1a2b3c4d5e6f7a8b9c0d2"]excludestring[] Reject these companies (same idvalues). Max 20000 ids.nameobjectoptionalMatch by company name. Exact, case-insensitive list lookup. A value shaped like a website ("stripe.com", "https://www.stripe.com/about") also matches the company on that domain.
Field Type Description includestring[] Match companies whose value is in this list - any single value qualifies (exact, case-insensitive). Optional - provide include and/or exclude. Max 500 items. excludestring[] Reject companies whose value is in this list (exact, case-insensitive). 0-500 items. domainobjectoptionalMatch by web domain - host only, without scheme or www (e.g. "getprospect.com"). Every domain attached to a company is considered, not just the primary one.
Field Type Description includestring[] Match companies whose value is in this list - any single value qualifies (exact, case-insensitive). Optional - provide include and/or exclude. Max 500 items. excludestring[] Reject companies whose value is in this list (exact, case-insensitive). 0-500 items. linkedin_idobjectoptionalMatch by LinkedIn's numeric company id. Company URLs go through Company Enrich first - see
id.Field Type Description includeinteger[] Match these LinkedIn companies. LinkedIn's numeric company id. Company URLs are not accepted here - enrich the company by linkedin_urlfirst, then filter by theidthat comes back. Max 500 items.Example:
[162479]excludeinteger[] Reject these LinkedIn companies. LinkedIn's numeric company id. Company URLs are not accepted here - enrich the company by linkedin_urlfirst, then filter by theidthat comes back. Max 500 items.
Example
{ "filters": { "company": { "domain": { "include": [ "intercom.com", "stripe.com" ] } } } }company_industryobjectoptionalIndustry name, or one of the category GROUP names Industries groups them under - a group matches every industry in that category. Same vocabulary as People Search's own company_industry.
Field Type Description includestring[] Match companies whose value is in this list - any single value qualifies (exact, case-insensitive). Optional - provide include and/or exclude. Max 500 items. excludestring[] Reject companies whose value is in this list (exact, case-insensitive). 0-500 items. Example
{ "filters": { "company_industry": { "include": [ "Software & Internet", "IT Services & IT Consulting" ], "exclude": [ "Staffing & Recruiting" ] } } }company_typeobjectoptionalCompany legal/ownership type (see Company types). Values match case-insensitively.
Field Type Description includeenum[] Company types to match (any of). Allowed values:
Privately HeldPublic CompanyNon ProfitSelf OwnedSelf EmployedPartnershipEducationalGovernment AgencyUnknownexcludeenum[] Company types to reject. Allowed values:
Privately HeldPublic CompanyNon ProfitSelf OwnedSelf EmployedPartnershipEducationalGovernment AgencyUnknownExample
{ "filters": { "company_type": { "include": [ "Privately Held", "Public Company" ] } } }company_business_typeobjectoptionalAudience type (see Business types). Values: B2B, B2C, Nonprofit, Unknown.
Field Type Description includeenum[] Business types to match (any of). Allowed values:
B2BB2CNonprofitUnknownexcludeenum[] Business types to reject. Allowed values:
B2BB2CNonprofitUnknownExample
{ "filters": { "company_business_type": { "include": [ "B2B" ] } } }company_revenue_streamobjectoptionalRevenue model (see Revenue streams). Values match case-insensitively.
Field Type Description includeenum[] Revenue streams to match (any of). Allowed values:
Professional ServicesProduct SalesGrants / DonationsSubscriptions / RecurringProject / Contract WorkEvent / Experience RevenueTransaction FeesRental / LeasingAdvertisingFinancial ServicesLicensing / IPUnknownexcludeenum[] Revenue streams to reject. Allowed values:
Professional ServicesProduct SalesGrants / DonationsSubscriptions / RecurringProject / Contract WorkEvent / Experience RevenueTransaction FeesRental / LeasingAdvertisingFinancial ServicesLicensing / IPUnknownExample
{ "filters": { "company_revenue_stream": { "include": [ "Subscriptions / Recurring", "Product Sales" ] } } }company_countryobjectoptionalCountry as ISO-3166-1 alpha-2 codes (see Countries). Matches any office location by default; set
headquarters_only: trueto match the registered headquarters country only.Field Type Description includestring[] Match companies whose value is in this list - any single value qualifies (exact, case-insensitive). Optional - provide include and/or exclude. Max 500 items. excludestring[] Reject companies whose value is in this list (exact, case-insensitive). 0-500 items. headquarters_onlyboolean When true, match the company headquarters country only. When false (default), any office country we have resolved counts, headquarters included: includes widen (a company with an office there matches) and excludes tighten symmetrically (a company with an office there is rejected). default: false. Example
{ "filters": { "company_country": { "include": [ "US", "CA" ], "headquarters_only": true } } }company_locationobjectoptionalCompany location as unified location strings - a country ("United States"), a state ("Texas, United States"), a city ("San Francisco, California, United States") or a region ("EMEA"). Same format and vocabulary as People Search's company_location and person_location. Any resolved office counts by default; see headquarters_only. Use
company_countryinstead when you already hold ISO-3166-1 alpha-2 codes.Field Type Description includestring[] Match these locations (any of). Unified strings like "United States", "Texas, United States", "San Francisco, California, United States" - or a region like "EMEA", "APAC", "Europe", "Latin America", which expands to its member countries (full list with member countries: GET /v2/enums/regions). Max 100 items, each 2-200 chars. If none of the values resolve to a known location, the request fails with 400. excludestring[] Reject these locations (same unified-string format). Max 100 items, each 2-200 chars. Values that do not resolve are skipped. headquarters_onlyboolean When true, match the company headquarters location only. When false (default), any office location we have resolved counts, headquarters included: includes widen (a company with an office there matches) and excludes tighten symmetrically (a company with an office there is rejected). default: false. Example
{ "filters": { "company_location": { "include": [ "San Francisco, California, United States" ], "headquarters_only": true } } }company_headcount_rangeenum[]optionalBucketed headcount range (see Employee ranges). 1-8 buckets.
Example
{ "filters": { "company_headcount_range": [ "51-200", "201-500" ] } }company_headcount_customobjectoptionalRaw headcount range. min/max are inclusive; either may be omitted.
Field Type Description minnumber Lower bound (inclusive). Optional. maxnumber Upper bound (inclusive). Must be >= min. Optional. Example
{ "filters": { "company_headcount_custom": { "min": 100, "max": 5000 } } }company_foundedobjectoptionalFounded year range. min/max are inclusive; either may be omitted.
Field Type Description minnumber Lower bound (inclusive). Optional. maxnumber Upper bound (inclusive). Must be >= min. Optional. Example
{ "filters": { "company_founded": { "min": 2010, "max": 2020 } } }company_naicsobjectoptionalNAICS codes (numeric). Matches when any of the company's codes is in the list.
Field Type Description includenumber[] Match companies whose value is in this list - any single value qualifies. Optional - provide include and/or exclude. Max 500 items. excludenumber[] Reject companies whose value is in this list. 0-500 items. Example
{ "filters": { "company_naics": { "include": [ 541511, 541512 ] } } }company_technologiesobjectoptionalWeb technologies detected on the company website, by id: the
valueof aPOST /v2/search/suggestrow withtype: technologyandkind: technology. Websites are rescanned every 30 days.Field Type Description includestring[] Technology ids to match. match_mode: ANY(default): a company using any of them qualifies;ALL: it must use every one. Max 500.Example:
["3421"]excludestring[] Reject companies using any of these technology ids. Max 500. match_modeenum How includecombines:ANY(default) - at least one;ALL- every one, on the same company.Allowed values:
ANYALLExample
{ "filters": { "company_technologies": { "include": [ "3421" ], "match_mode": "ANY" } } }company_technology_categoriesobjectoptionalTechnology categories (CMS, Ecommerce, Analytics, ...), by id: the
valueof a suggest row withkind: category. A category matches a company using any technology in it.Field Type Description includestring[] Category ids to match (any of). Max 200. Example:
["1"]excludestring[] Reject companies using any technology in these category ids. Max 200. Example
{ "filters": { "company_technology_categories": { "include": [ "1" ] } } }company_keywordsobjectoptionalFree-text keyword match across selected source fields (see Keyword sources). When this filter is active, results are ranked by relevance first.
Field Type Description includestring[]required Phrases to search for. 1-20 items, 3-100 chars each. Matched as phrases: a multi-word entry like "email finder" requires those words adjacent and in order within one of the selected source fields, not merely present somewhere in it. excludestring[] Phrases that disqualify a company. 0-20 items. Matched as phrases, same as include.include_allboolean When true, every phrase in includemust match; otherwise any single match qualifies. default: false.sourcesenum[] Restrict matching to these source fields (see Keyword sources). Omit to use the default source set - see this company_keywordsfilter's own description above for what that is.Example
{ "filters": { "company_keywords": { "include": [ "customer support", "help desk" ], "include_all": true, "sources": [ "specialties" ] } } }
sort_byenumoptionalSort key. Omit for the smart default: relevance when
filters.company_keywordsis present, followers desc otherwise.Allowed values:
company_namecompany_employee_countcompany_industrycompany_countrycompany_foundedcompany_saved_atsort_directionenumoptionalSort direction. Per-key defaults apply; ignored when sort_by is omitted.
Allowed values:
ascdescpageintegeroptionalmin: 1max: 1000default: 1Page number, 1-based. The deepest reachable page is 25,000 / per_page: 1,000 at 25, 500 at 50 and 250 at 100 (metadata.pagination.max_page). A result set that runs past it has total_pages clamped to max_page and pagination.truncated=true, while total_count stays the real match count - narrow the filters to reach the rest.
per_pageenumoptionaldefault: 25Results per page: 25, 50 or 100.
Allowed values:
2550100
Responses
For error handling see Errors. Response objects are described in Person object and Company object.
