Skip to main content
POST
Count people matching a search (free)

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, as POST /prospects/search takes it: filters, savedSearchId, savedSearchName or query. A count has no paging and no linkedinUrl lookup.

filters
object

Literal filters, one of the four filter sources, in the vocabulary of POST /prospects/search. People filters in the search vocabulary: include/exclude fields take [{ status, value }] entries, term fields a string or an array of strings, rangeInputs { min, max } ranges — every field and its accepted values are listed by GET /prospects/filter-options. On this endpoint a value outside a field's listed vocabulary is refused with 422 VALIDATION_FAILED, naming the field and the value, before anything is billed; so is a filter the search no longer serves (sex, github_url, github_username, facebook_url, job_title_sub_role, experience.title.sub_role, experience.company.industry, experience.company.location.country, experience.company.location.name, experience.company.location.continent, experience.company.type, location_continent, job_company_location_continent) and an exclude entry on education.degrees (the degree filter takes includes only; size and revenue excludes are searched). One exception: languages.name also accepts these other names of listed languages, searched as the listed one: bangla, farsi, panjabi, slovene, chinese, mandarin, putonghua, tagalog, filipino, sinhala, khmer, central khmer, hakka chinese, hokkien, taiwanese, newari, northern frisian, western frisian, ndebele, north ndebele, south ndebele, assyrian neo-aramaic. Must contain at least one non-empty value.

savedSearchId
string

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

savedSearchName
string

Exact title of one of your people 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 who 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

Response

Success

status
enum<string>
required

ready (200) with the total, or pending (202) while the count runs: repeat the request.

Available options:
ready,
pending
total
integer | null
required

People matching the filters; null while pending.

filters
object
required

The filters counted, in the POST /prospects/search vocabulary.

creditsCharged
integer
required

Always 0: counting is free.

unresolvedCriteria
string[]

Only with query: the parts of the sentence no filter could express.

closestCompanyMatches
object[]

Only with query: each company the sentence named that Smart Search chose between same-named companies for, and the one it chose; empty when it guessed nothing.

ignoredFilterKeys
string[]

Only with a saved search: stored keys with no search field, left out of the count.