Bulk Verify Leads

Verify the email addresses of up to 10,000 leads in the background.

POSThttps://api.foxreach.io/api/v1/leads/bulk/verify

Requires an API key with the write scope.

Starts a background verification run and saves each verdict on its lead. This spends verification credits: one per good or bad verdict, nothing for unknown or error. The call checks that your plan allows verification and that your balance covers the whole selection before it queues anything.

The response is a 202 with an email_verification job. Poll Get Job; its result carries good, risky, bad, errors and billableCount when it completes. Leads that are not in your workspace are ignored.

Body Parameters#

leadIdsstring[]body

Lead IDs, up to 50,000. Send this or filter, not both.

filterobjectbody

Select leads by filter instead. Keys: search, status, tags (comma separated; a lead must carry all of them), provider, interestStatus, labelId. Matches at most 50,000 leads, newest first.

Response#

dataobject

The job (type email_verification, status pending). totalItems is the number of leads queued.

Errors#

Status	Description
`401`	Missing, invalid, revoked or expired API key
`403`	API key does not have the required scope: `write`
`400`	More than 10,000 leads selected, or none of them are in this workspace
`402`	Not enough verification credits, or the plan does not include verification
`422`	Neither or both of `leadIds` and `filter` were sent

Rate Limit#

100 requests per minute, shared by every bulk 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 (bulk).
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

curl -X POST "https://api.foxreach.io/api/v1/leads/bulk/verify" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"filter": {"status": "active"}}'

Python SDK

from foxreach import FoxReach

client = FoxReach(api_key="otr_your_key")
job = client.leads.bulk_verify(filter={"status": "active"})

TypeScript SDK

import { FoxReach } from "foxreach";

const client = new FoxReach({ apiKey: "otr_your_key" });
const job = await client.leads.bulkVerify({ filter: { status: "active" } });

Response

JSON

{
  "data": {
    "id": "cmjob903",
    "type": "email_verification",
    "status": "pending",
    "progress": 0,
    "totalItems": 840,
    "completedItems": 0,
    "result": null,
    "error": null,
    "startedAt": null,
    "completedAt": null,
    "createdAt": "2026-11-04T09:00:00"
  }
}

Was this page helpful?

View as MarkdownLast updated November 4, 2026