Skip to main content
POST
Run a company search

Authorizations

Authorization
string
header
required

Your API token (af_…) as the Basic-auth username, with an empty password.

Body

application/json

Exactly one filter source — filters, savedSearchId, savedSearchName or query — plus optional paging.

filters
object

Literal filters, one of the four filter sources. Company filters in the search vocabulary: include/exclude fields take [{ status, value, label }] entries (label is required), list fields arrays of strings, ranges { min, max } and date ranges { start, end } — enum vocabularies come from GET /companies/filter-options, names and places from GET /companies/autocomplete. Must contain at least one non-empty value.

savedSearchId
string

Id of one of your COMPANY saved searches to take the filters from instead of filters (a people saved search answers 422 SAVED_SEARCH_TYPE_MISMATCH).

savedSearchName
string

Exact title of one of your company saved searches to take the filters from instead of filters; two searches sharing the title answer 409 SAVED_SEARCH_NAME_AMBIGUOUS.

Required string length: 1 - 255
query
string

Natural-language description of the companies to find (max 2000 chars), converted into filters server-side instead of filters; criteria that could not be mapped come back as unresolvedCriteria, and a query yielding no filter answers 422 QUERY_FILTERS_INVALID.

Required string length: 1 - 2000
size
integer
default:25

Companies per page (1-100, default 25); the search pre-checks 2 credits per requested company and debits 2 credits per company returned.

Required range: 1 <= x <= 100
cursor
string | null

The nextCursor returned by the previous page, sent together with the same filter source; null (default) starts from the first page. The match total is only counted on the first page — it comes back null on every cursor page.

Response

Success

companies
object[]
required
total
integer | null
required

True match count on the first page; null on every cursor page, where the upstream does not count.

nextCursor
string | null
required

Send back as cursor with the same filter source for the next page; null on the last page.

filters
object
required

The RESOLVED filters the search actually ran.

unresolvedCriteria
string[]

Only when the source was query: criteria in the prose that could not be turned into a filter.