Run a company search

The company twin of the people search. The filter source is exactly one of: literal filters, a stored COMPANY saved search (savedSearchId / savedSearchName), or a natural-language query (converted into filters server-side; criteria it could not map come back as unresolvedCriteria). A people saved search answers 422 SAVED_SEARCH_TYPE_MISMATCH.

The response always echoes the RESOLVED filters. Page by re-sending the same filter source together with the returned nextCursor as cursor; nextCursor is null on the last page. total is the true match count and is only counted on the FIRST page — every cursor page answers total: null, so read the count once and carry it.

Rows are the provider's company record (snake_case, ~80 fields, varying by company: names, domains, LinkedIn metadata, industries, NAICS codes, headcount and revenue estimates, funding, technologies, headquarters location) plus Fuse's isSaved, which says whether the company is already in one of your company lists.

filters.headquartersCity names are geocoded one by one and the resulting city areas are OR-ed together; a name that geocodes to nothing is dropped and the search runs on the rest, so take the values from GET /companies/autocomplete?field=location. Only when not one name resolves is the search refused with 422 CITY_FILTER_UNRESOLVED. employeeCountV2 is the one range whose lower bound is exclusive: { min: 50 } matches companies with more than 50 employees.

Billing: 2 credits per requested company are pre-checked and 2 credits per company returned are debited.

Errors:

• 402 INSUFFICIENT_CREDITS — The balance does not cover the pre-check for this request; nothing was billed.
• 404 SAVED_SEARCH_NOT_FOUND — No saved search of yours has that id or exact title.
• 409 SAVED_SEARCH_NAME_AMBIGUOUS — Two of your saved searches share that title — reference it by savedSearchId instead.
• 422 VALIDATION_FAILED — The request failed the declared schema; param names the offending key and message quotes the rule it broke.
• 422 SAVED_SEARCH_TYPE_MISMATCH — The saved search exists but stores the other kind of filters; param is savedSearchId.
• 422 SAVED_SEARCH_INVALID — The STORED filters no longer form a runnable company search — the blob is empty, or every value in it was retired. A filterless stored search is refused here rather than run as a whole-universe search.
• 422 QUERY_FILTERS_INVALID — The natural-language query produced no usable filter; name concrete criteria.
• 422 CITY_FILTER_UNRESOLVED — NOT ONE of the filters.headquartersCity names geocoded to a city area, so the search was refused rather than run worldwide; names that do geocode are OR-ed together and a name that does not is dropped, so this fires only when every name fails. param is filters.headquartersCity.
• 429 RATE_LIMITED — Per-token rate limit for this bucket exhausted; retry after the window in the RateLimit-Reset header.
• 500 UNEXPECTED_ERROR — The request failed inside the service; nothing was billed and the request_id identifies the failure.

Requires one of the following token scopes: companies.