Run a people search

Find people by a plain-English sentence or by filters (job title, seniority, department, employer, industry, location, company size): name, title, employer and LinkedIn URL for each match, 1 credit per person returned. The filter source is exactly one of: literal filters, a stored PEOPLE saved search (savedSearchId or savedSearchName), or a natural-language query (the product’s smart search converts the prose into filters; criteria it could not map come back as unresolvedCriteria, and each company it chose between same-named companies for comes back in closestCompanyMatches as { requestedName, name, domain }). Sending two sources is a 422. A saved search resolves to its filters and echoes ignoredFilterKeys for stored keys with no search field, the filters the search no longer serves included (those are dropped from a saved search or a query, but refused with 422 VALIDATION_FAILED in literal filters); a company saved search answers 422 SAVED_SEARCH_TYPE_MISMATCH.

The response always echoes the RESOLVED filters — reuse them verbatim to page, refine, or POST /prospects/search/save-to-list — plus total, an estimate of the matches (null when unknown: on a search with employer filters, and on every page after the first), and a scrollToken for the next page (send it back with the returned filters; resending a query converts it again, which is slower and can build a different search that answers 422 SEARCH_CHANGED; it is null when there are no more pages). A page can hold fewer rows than size; only a null token marks the end. First and last names and full_name match fuzzily; months in current role (job_start_date) means started within the last N months; work_email, personal_emails and mobile_phone look up the person who has that email address or phone number, then search that person with every other filter. filters.company_filters narrows the search to people whose current employer matches company search’s own filters (funding stage, status, tags, technologies, investors, accelerators, industries, NAICS codes, office countries, the Fortune 500 or Forbes Global 2000, last funding, founding and last-funding dates, LinkedIn slugs), in the vocabulary of GET /companies/filter-options; a key it does not offer, or a value off a fixed list, is refused with 422 VALIDATION_FAILED naming it.

Company names: an entry carrying liOrgId or domain (as GET /prospects/autocomplete?field=company returns them) matches that company; a name alone matches every company with exactly that name, from Fuse’s own company records and the provider’s earlier answers, and otherwise looked up on the provider, at most 500 such lookups per filter per request (an excluded name is always also asked of the provider). Included names left out (nobody has them, past the 500 lookups, or out of time) do not stop the search: the rest is searched and unappliedCompanyNames says how many of each filter were left out and how many are still to look up; sending the same request again looks the next ones up and applies more. Excluded names left unresolved refuse the search with 422 COMPANY_EXCLUDES_UNRESOLVED, since running without them would return the people they exclude. A request has about 28 s; past it the search answers 503 when its own lookups ran out of time (a retry gets further) and 504 when the provider did.

Every row has the same fields, in snake_case with the vocabulary of GET /prospects/filter-options: linkedin_url (the person’s key), names, the current job (title, level, department and sub-department worked out from the title, employer name, domain and industry), industry, a lower-case location, summary, job history and a profile picture link; a field with no value is left out. linkedinMemberId is the person’s LinkedIn member id; rows carry no pdlId. Fuse adds savedProfile / savedBy (whether this person is already a contact of yours, matched by LinkedIn URL) and linkedinConnectedAccountIds / linkedinInvitationSentAccountIds (which of your connected LinkedIn accounts already reached them). Rows carry no email address or phone number — searching is discovery only. Contact details you have already enriched for some of these people are stripped too, so a row never depends on your enrichment history; use /prospects/search/save-to-list with enrich to obtain contact details.

Billing: 1 credit per requested profile is pre-checked and 1 credit per profile returned is debited. (Enforced by the public row transformer, which removes Fuse’s enrichment overlay before the row is returned.)

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 search — every value was retired, or the blob translates to nothing.
• 422 QUERY_FILTERS_INVALID — The natural-language query produced no usable filter; name concrete criteria.
• 422 SEARCH_FILTERS_INVALID — The provider rejected the assembled query as malformed — a filter value is the wrong shape for its field. Also a vocabulary filter holding only values the search cannot serve; then param names the filter and values lists them.
• 422 FILTER_VALUE_UNRESOLVED — No company, place or LinkedIn profile named in one filter could be found, or no value of an email or phone filter is an email address or a phone number, so the search was refused instead of run without it; param names the filter (or linkedinUrl) and values lists the values nothing matched. Take company, place and profile values from GET /prospects/autocomplete.
• 422 SCROLL_TOKEN_INVALID — scrollToken is not one this API issued (a token from an earlier version of the search included), so the search cannot continue from it; nothing was billed. Start again without scrollToken.
• 422 COMPANY_EXCLUDES_UNRESOLVED — Excluded company names could not be identified (past the 500 per filter a search looks up beyond our own company records, out of time, or the lookup failed), so the search was refused rather than return the people they exclude; param names the first such filter. Nothing was billed. Retry, exclude companies by the identity GET /prospects/autocomplete returns, or exclude fewer by name.
• 422 SEARCH_CHANGED — The filters no longer build the search the scrollToken came from (they, or the companies they name, changed since its first page), so it cannot continue; nothing was billed. Start again without scrollToken.
• 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.
• 503 UNEXPECTED_ERROR — Looking up the company names, email addresses or phone numbers in the filters took longer than the request allows; nothing was billed. Send the same request again: the lookups that finished are kept, so the retry gets further.
• 504 UNEXPECTED_ERROR — The search provider took too long and the search was stopped; nothing was billed. Narrow it (a job title or location, or fewer company_filters) and search again.

Requires one of the following token scopes: search.