Skip to content
Docs

List Reveals

The workspace's reveal history for one month, newest first.

GEThttps://api.foxreach.io/api/v1/lead-finder/reveals

Requires an API key with the read scope.

Query Parameters#

monthstringquery

Month as YYYY-MM, from 2020-01 to 2100-12. Defaults to the current month.

statusstringquery

found, returned (not found or errored) or pending.

qstringquery

Substring match on first name, last name, email or company.

pageintegerqueryDefault: 1

Page number, starting at 1.

pageSizeintegerqueryDefault: 50

Rows per page. Values above 100 are capped at 100.

Response#

dataobject

One page of history.

Show data
revealsarray

The rows.

Show reveals
idstring
Reveal identifier. Use it as a revealIds entry.
batchIdstring
Batch the reveal belongs to.
personIdstring
Provider person id.
firstNamestring
First name.
lastNamestring
Last name.
titlestring
Job title.
companystring
Company.
companyDomainstring
Company domain.
linkedinUrlstring
LinkedIn URL.
statusstring
pending, found, not_found or error.
emailstring
The email, once found.
certaintystring
Confidence in the email: ultra_sure, very_sure or probable.
failureReasonstring
Why a reveal returned nothing or was refunded, for example already_in_leads.
leadIdstring
The active lead for this email, or null.
inLeadsboolean
Whether an active lead exists.
creditsChargedinteger
Credits charged for this row.
createdAtstring
ISO 8601 timestamp.
completedAtstring
ISO 8601 timestamp, or null while pending.
campaignNamestring
Campaign the reveal was made into, or null.
nowInstring
Where a found person is now: the campaign name, Leads or Lead Finder only. null otherwise.
totalinteger
Rows matching the filters.
pageinteger
Current page.
pageSizeinteger
Rows per page.
summaryobject
Totals for the whole month, ignoring status and q: month, reveals, found, notFound, pending, creditsUsed, inCampaign.

Errors#

StatusDescription
401Missing, invalid, revoked or expired API key
403API key does not have the required scope: read
404Lead Finder is not enabled while Lead Finder is switched off on this environment
422month must be YYYY-MM or status must be found, returned or pending
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