Person Search
Find people matching a free-text query, then resolve each hit into a full profile
Endpoint
One endpoint for every offer below. Omit provider and the router picks with automatic failover — the response's served_by tells you which one ran.
https://api.socialrouter.io/v1/enrich/person/searchOffers
Every offer below returns the same normalized output, in failover order — the first one serves unless you pin another with the provider field.
apollo/personvia Apollodefault routeUp to 1 queries per request
your own keyyou bring it
Parameters
JSON body of the request. Unknown fields and unknown options are rejected with the valid list, so a wrong guess costs nothing.
| Parameter | Type | Description |
|---|---|---|
queriesRequired | string[] | Search queries to process. Accepted shape:Free-text keywords describing the people to find. Narrow with the options below rather than by writing a longer queryExample: growth engineerA single query string is accepted too. |
providerOptional | string | Pin one offer, e.g. apollo/person. Omit it and the router picks with failover. |
limitOptional | integer | Max records to return per query. |
optionsOptional | object | Service-specific options, listed below. |
options.titlesOptional | string | Comma-separated job titles. Similar titles are matched too, e.g. "head of growth, growth lead". |
options.senioritiesOptional | string | Comma-separated seniority levels: owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern. |
options.locationsOptional | string | Comma-separated locations the person lives in, e.g. "Paris, London". |
options.companyLocationsOptional | string | Comma-separated locations of the employer's headquarters. |
options.companyDomainsOptional | string | Comma-separated employer domains, e.g. "stripe.com, figma.com". |
options.employeeRangeOptional | min,max | Employer headcount range, e.g. "11,50". |
options.emailStatusOptional | verified | unverified | likely_to_engage | unavailable | Only people whose work email has this status. |
options.enrichOptional | boolean | Resolve each hit into a full profile, which is the only way to obtain a LinkedIn URL and an unmasked name. Consumes 1 credit per person matched on your own provider account. Set false for a credit-free preview: masked last names, no LinkedIn URL, is_obfuscated: true on every record. Defaults to true. |
options.revealPersonalEmailsOptional | boolean | Also return personal email addresses. Consumes extra credits on your own provider account. Defaults to false. |
Going further
Auth, error semantics, and every other endpoint live in the API reference — including the machine-readable OpenAPI spec at /v1/openapi.json.
Frequently asked questions
How much does Person search cost?
SocialRouter bills nothing per record for this service: every offer runs on a provider key you register yourself, and the records are invoiced to you by that provider directly.
Which offers serve person/search?
apollo/person — 1 offer is available behind the same endpoint. Pin one with the optional "provider" field, or omit it and the router picks with automatic failover. The response's "served_by" field names the offer that ran.
What input does it need?
The "queries" field of the JSON body, as an array of strings: Free-text keywords describing the people to find. Narrow with the options below rather than by writing a longer query. For example: growth engineer
Is the output format the same for every offer?
Yes. Every offer returns the normalized record schema documented on this page; some add extra platform-specific fields on top, but the documented fields are always present.
How many queries can I send per request?
Up to 1 queries in a single request, depending on the offer.
What happens if an offer fails?
SocialRouter automatically fails over to the next offer serving the same service, so a single upstream outage doesn't break your integration.
What options does it take?
titles (string): Comma-separated job titles. Similar titles are matched too, e.g. "head of growth, growth lead". seniorities (string): Comma-separated seniority levels: owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern. locations (string): Comma-separated locations the person lives in, e.g. "Paris, London". companyLocations (string): Comma-separated locations of the employer's headquarters. companyDomains (string): Comma-separated employer domains, e.g. "stripe.com, figma.com". employeeRange (string): Employer headcount range, e.g. "11,50". emailStatus (verified|unverified|likely_to_engage|unavailable): Only people whose work email has this status. enrich (boolean): Resolve each hit into a full profile, which is the only way to obtain a LinkedIn URL and an unmasked name. Consumes 1 credit per person matched on your own provider account. Set false for a credit-free preview: masked last names, no LinkedIn URL, is_obfuscated: true on every record. revealPersonalEmails (boolean): Also return personal email addresses. Consumes extra credits on your own provider account.