Reveal List Emails

Reveal work emails for people saved in a list. Spends reveal credits.

POSThttps://api.foxreach.io/api/v1/lead-finder/lists/{list_id}/reveal

Requires an API key with the write scope.

This spends reveal credits, exactly like Reveal Emails: one credit for each person whose email is newly looked up, taken from the oldest credit bucket first. Misses are refunded. People already revealed in this workspace cost nothing. Only a people list can be revealed.

Path Parameters#

list_idstringpathrequired

The list id.

Body Parameters#

keysarraybodyrequired

1 to 100 item keys from the list.

campaignIdstringbody

Also place found people in this campaign. It must belong to the workspace.

Response#

dataobject

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`
`403`	`upgrade_required` on the Free plan
`404`	`Lead Finder is not enabled` while Lead Finder is switched off on this environment
`503`	`Lead Finder is not configured` when it is enabled but has no data provider key
`404`	`List not found`: the list does not exist in this workspace
`404`	`Campaign not found` when `campaignId` is not in this workspace
`422`	`keys` is empty or longer than 100, or the list is a company list

Rate Limit#

100 requests per minute, shared by every expensive call in your workspace. Fixed 60-second window.
Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unix epoch seconds) and X-RateLimit-Bucket (expensive).
A 429 response includes a Retry-After header (seconds until the bucket resets).

For client-side patterns, see Rate Limiting.

Request

cURL

curl -X POST "https://api.foxreach.io/api/v1/lead-finder/lists/lst_abc123/reveal" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["https://www.linkedin.com/in/ada"]}'

Python SDK

from foxreach import FoxReach

client = FoxReach(api_key="otr_your_key")
result = client.lead_finder.reveal_list("lst_abc123", keys=["https://www.linkedin.com/in/ada"])

TypeScript SDK

import { FoxReach } from "foxreach";

const client = new FoxReach({ apiKey: "otr_your_key" });
const result = await client.leadFinder.revealList("lst_abc123", { keys: ["https://www.linkedin.com/in/ada"] });

Response

JSON

{
  "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 4, 2026