List Leads
Retrieve a paginated list of leads in your workspace.
https://api.foxreach.io/ api/ v1/ leadsQuery Parameters#
pageintegerquerydefault 1Page number (starts at 1).
pageSizeintegerquerydefault 50Number of leads per page (1-100).
emailstringqueryExact case-insensitive email match. Returns only leads whose email address equals this value. Use this for lookup-by-email (e.g., Zapier "Find Lead" step). % and _ are matched literally. If you also pass search, a lead must match both.
searchstringquerySubstring search across email, first name, last name, and company.
statusstringqueryFilter by lead status: active, bounced, unsubscribed, or replied.
tagsstringqueryComma-separated tag names, for example warm,webinar. Returns leads that have any of the given tags. Names are trimmed and matched in lowercase, so Warm and warm are the same tag. At most 50 tags, each at most 100 characters. Combines with the other filters: a lead must match all of the filters you pass. See List Tags for the tags in your workspace.
providerstringqueryFilter by the mail provider that hosts the lead's email address: google, microsoft, zoho, yahoo (Yahoo and AOL), godaddy, other, gateway, or unresolved. gateway returns leads whose mail goes through a security filter such as Proofpoint, Mimecast or Barracuda, whatever provider sits behind it. unresolved returns leads whose provider is not checked yet. The filter only reads: unchecked domains are checked when someone filters by provider on the Leads page in FoxReach or a campaign with provider matching runs, so a lead can move from unresolved to its provider later. Counts per provider: Get Lead Mail Providers.
interestStatusstringqueryFilter by interest status: interested, not_interested or out_of_office. The status is set from the lead's newest categorized reply, or by hand (see Update Lead).
labelIdstringqueryOnly leads that carry this lead label. Ids come from List Lead Labels.
Response#
dataarrayArray of lead objects.
Show Lead object
idstringemailstringfirstNamestringlastNamestringcompanystringtitlestringphonestringlinkedinUrlstringwebsitestringcustomFieldsobjectnotesstringsourcestringapi, csv_import, manual).statusstringcreatedAtstringupdatedAtstringmetaobjectPagination metadata.
Show Meta object
pageintegerpageSizeintegertotalintegertotalPagesintegerErrors#
| Status | Description |
|---|---|
422 | Invalid query parameter (e.g., pageSize over 100) |
429 | Rate limit exceeded, see Rate Limit section below |
Rate Limit#
- 300 requests per minute, shared by every
readcall in your workspace. Fixed 60-second window. - Every response includes
X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset(unix epoch seconds) andX-RateLimit-Bucket(read). - A
429response includes aRetry-Afterheader (seconds until the bucket resets).
For client-side patterns (Retry-After, exponential backoff, monitoring X-RateLimit-Remaining), see Rate Limiting.