Add Revealed People to Leads

Turn revealed people into leads. Free and safe to repeat.

POSThttps://api.foxreach.io/api/v1/lead-finder/add-to-leads

Requires an API key with the write scope.

Revealing alone never creates a lead; this call does. Only reveals that found an email count. It costs no credits and can be repeated: people who are already active leads are counted, not duplicated, and a deleted lead is restored. The plan's contact limit is checked once for the whole call, counting only people who are not leads yet. If the call would go over the limit, nothing is added.

Send revealIds, personIds or both, up to 5,000 in total.

Body Parameters#

revealIdsarraybody

Reveal ids from List Reveals or a batch.

personIdsarraybody

Person ids from a search result, for people already revealed in this workspace.

campaignIdstringbody

A campaign in this workspace. The people are also added to it.

Response#

dataobject

What happened.

Show data

addedinteger

New leads created.

restoredinteger

Deleted leads brought back.

alreadyInLeadsinteger

People who were already active leads.

skippedinteger

Ids that were not found as a revealed email in this workspace.

addedToCampaigninteger

People added to campaignId.

Errors#

Status	Description
`401`	Missing, invalid, revoked or expired API key
`403`	API key does not have the required scope: `write`
`400`	`Pick at least one revealed person` when both id lists are empty, or `At most 5000 people per call`
`403`	`upgrade_required` with `limit`, `current` and `requested` when the contact limit would be exceeded. 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
`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/add-to-leads" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"personIds": ["per_abc123"], "campaignId": "cmp_abc123"}'

from foxreach import FoxReach

client = FoxReach(api_key="otr_your_key")
result = client.lead_finder.add_to_leads(person_ids=["per_abc123"], campaign_id="cmp_abc123")

import { FoxReach } from "foxreach";

const client = new FoxReach({ apiKey: "otr_your_key" });
const result = await client.leadFinder.addToLeads({ personIds: ["per_abc123"], campaignId: "cmp_abc123" });

Response

{
  "data": {
    "added": 1,
    "restored": 0,
    "alreadyInLeads": 0,
    "skipped": 0,
    "addedToCampaign": 1
  }
}

Was this page helpful?

View as MarkdownLast updated November 2, 2026