Skip to content
Docs

Search People

Search the people database. One call uses one page of the daily search budget.

POSThttps://api.foxreach.io/api/v1/lead-finder/search

Requires an API key with the read scope.

Each call fetches one page and counts against the workspace's daily search budget. The budget grows with the reveals you make that day; Get Credits shows today's usage. Emails are not included in search results: reveal them with Reveal Emails. It needs a paid plan. filters is an object of filter keys. Call Get Filter Options for the full list of keys and the allowed values for industries and company types. A value outside the provider's vocabulary matches nothing and returns zero rows rather than an error.

Body Parameters#

filtersobjectbodyrequired

Person filters, for example {"jobTitles": ["CTO"], "countries": ["US"]}. At least one filter besides countries is required. companyIds accepts at most 200 entries.

pageSizeintegerbodyDefault: 25

Results per page, 1 to 50.

pageTokenstringbody

The nextPageToken from the previous page.

Response#

dataobject

One page of results.

Show data
totalinteger
Matching people across all pages.
peoplearray

The page.

Show people
idstring
Person identifier. Pass it to Reveal Emails.
firstNamestring
First name.
lastNamestring
Last name.
titlestring
Current job title.
companystring
Current company.
companyDomainstring
Company domain.
linkedinUrlstring
LinkedIn profile URL.
locationstring
Location.
industrystring
Industry.
companySizeinteger
Company headcount, or null when unknown.
headlinestring
Profile headline.
revealStatusstring
pending or found when this workspace has already revealed the person, otherwise null.
revealedEmailstring
The revealed email, once found.
inLeadsboolean
An active Lead exists for the revealed email right now.
leadIdstring
That Lead's identifier, or null.
nextPageTokenstring
Pass as pageToken for the next page. null on the last page.

Errors#

StatusDescription
401Missing, invalid, revoked or expired API key
403API key does not have the required scope: read
400country_not_available when a requested country is outside the covered list ({"detail": {"code": "country_not_available", "message": "...", "allowed": [], "blocked": []}}); unknown_filter_keys naming each key that does not exist ({"detail": {"code": "unknown_filter_keys", "message": "...", "unknownKeys": [], "validKeys": []}}); or a message asking for at least one filter besides countries
403upgrade_required on the Free plan: {"detail": {"code": "upgrade_required", "limit_type": "lead_finder", "message": "..."}}. A missing scope also returns 403 with a plain detail string
404Lead Finder is not enabled while Lead Finder is switched off on this environment
422More than 200 companyIds in one call (too_many_company_ids), or pageSize outside 1-50
429lead_finder_search_cap when today's search budget is used up: {"detail": {"code": "lead_finder_search_cap", "message": "...", "used": 20, "allowance": 20, "revealsToday": 0}}. Revealing emails raises the allowance, or retry tomorrow
502The data provider is unavailable right now
503Lead Finder is not configured when it is enabled but has no data provider key

Rate Limit#

  • 100 requests per minute, per API key. Fixed 60-second window.
  • Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (unix epoch seconds).
  • A 429 response includes a Retry-After header (seconds until the bucket resets).

For client-side patterns (Retry-After, exponential backoff, monitoring X-RateLimit-Remaining), see Rate Limiting.

Was this page helpful?
View as MarkdownLast updated November 2, 2026