Skip to content

List Leads

Retrieve a paginated list of leads in your workspace.

GET/api/v1/leads

Query Parameters#

pageintegerquerydefault 1

Page number (starts at 1).

pageSizeintegerquerydefault 50

Number of leads per page (1-100).

emailstringquery

Exact 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.

searchstringquery

Substring search across email, first name, last name, and company.

statusstringquery

Filter by lead status: active, bounced, unsubscribed, or replied.

tagsstringquery

Comma-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.

providerstringquery

Filter 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.

interestStatusstringquery

Filter 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).

labelIdstringquery

Only leads that carry this lead label. Ids come from List Lead Labels.

Response#

dataarray

Array of lead objects.

Show Lead object
idstring
Unique lead identifier.
emailstring
Lead's email address.
firstNamestring
First name.
lastNamestring
Last name.
companystring
Company name.
titlestring
Job title.
phonestring
Phone number.
linkedinUrlstring
LinkedIn profile URL.
websitestring
Website URL.
customFieldsobject
Custom key-value fields.
notesstring
Freeform notes.
sourcestring
How the lead was created (e.g., api, csv_import, manual).
statusstring
Lead status.
createdAtstring
ISO 8601 timestamp.
updatedAtstring
ISO 8601 timestamp.
metaobject

Pagination metadata.

Show Meta object
pageinteger
Current page number.
pageSizeinteger
Items per page.
totalinteger
Total number of leads.
totalPagesinteger
Total number of pages.

Errors#

StatusDescription
422Invalid query parameter (e.g., pageSize over 100)
429Rate limit exceeded, see Rate Limit section below

Rate Limit#

  • 300 requests per minute, shared by every read 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 (read).
  • 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.

Was this page helpful?
View as MarkdownLast updated November 6, 2026