Reveal Emails

Look up work emails for up to 100 people. Spends reveal credits.

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

Requires an API key with the write scope.

Takes person objects from a search result. Each newly charged person costs one reveal credit, taken from the workspace's credit buckets with the nearest expiry first. People already revealed in this workspace are reused at no cost, and people the provider cannot look up are not charged. It needs a paid plan.

The lookup runs in the background: the response reports what was requested and charged, and the emails arrive on the batch. Poll Get Reveal Batch with the returned batchId.

Body Parameters#

peoplearraybodyrequired

Between 1 and 100 person objects. Each needs id (up to 512 characters) and may carry firstName, lastName, title, company, companyDomain, linkedinUrl, location, industry and companySize. Pass the fields from the search result: a person can only be looked up with a first or last name plus a company or companyDomain.

campaignIdstringbody

A campaign in this workspace. Each person whose email is found becomes a lead and is added to this campaign. People revealed earlier are added right away.

Response#

dataobject

What was requested.

Show data

batchIdstring

Identifier to poll with Get Reveal Batch.

requestedinteger

Distinct people in the request.

chargedinteger

Credits spent on new lookups.

reusedinteger

People already revealed in this workspace.

inProgressinteger

People whose reveal is still pending from an earlier call.

unsearchableinteger

People with no name, or no company or company domain, who cannot be looked up.

balanceinteger

Credits left after this call.

addedToCampaigninteger

People already revealed who were added to campaignId immediately.

Errors#

Status	Description
`401`	Missing, invalid, revoked or expired API key
`403`	API key does not have the required scope: `write`
`402`	`insufficient_lead_finder_credits`: `{"detail": {"code": "insufficient_lead_finder_credits", "message": "...", "balance": 0, "required": 1}}`
`403`	`upgrade_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
`404`	`Lead Finder is not enabled` while Lead Finder is switched off on this environment
`404`	`Campaign not found` when `campaignId` is not in this workspace
`422`	`people` is empty or longer than 100, or a person has no `id`
`503`	`Lead 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.

Request

curl -X POST "https://api.foxreach.io/api/v1/lead-finder/reveal" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "people": [
      {"id": "per_abc123", "firstName": "Jane", "lastName": "Doe", "company": "Acme Inc", "companyDomain": "acme.com"}
    ]
  }'

from foxreach import FoxReach

client = FoxReach(api_key="otr_your_key")
result = client.lead_finder.reveal([
    {"id": "per_abc123", "firstName": "Jane", "lastName": "Doe", "company": "Acme Inc", "companyDomain": "acme.com"},
])

import { FoxReach } from "foxreach";

const client = new FoxReach({ apiKey: "otr_your_key" });
const result = await client.leadFinder.reveal({
  people: [{ id: "per_abc123", firstName: "Jane", lastName: "Doe", company: "Acme Inc", companyDomain: "acme.com" }],
});

Response

{
  "data": {
    "batchId": "bat_abc123",
    "requested": 1,
    "charged": 1,
    "reused": 0,
    "inProgress": 0,
    "unsearchable": 0,
    "balance": 99,
    "addedToCampaign": 0
  }
}

Was this page helpful?

View as MarkdownLast updated November 2, 2026