Skip to main content
GET
Get Leads in Campaign
CLI:

Overview

A single URL that owns the lead roster for a campaign:
  • GET — paginated list with optional status filter. Safe to poll.
  • POST — bulk add leads (1–1000 per call). Deduplicates by email (email campaigns) or LinkedIn URL (LinkedIn campaigns).
  • PATCH — edit one lead’s profile fields.
  • DELETE — remove leads by ID list (up to 500) or wipe the roster with { all: true }.
Every write method requires the campaign to be in draft status. Once the campaign transitions to launching/active/paused/completed, the roster is frozen — the API will return 400 on any mutation.

AI agent notes

Channel identity. Every lead needs the identity field matching the campaign type: email for email campaigns, linkedin_url for LinkedIn campaigns. Rows missing the required identity are rejected with a 400 naming the offending index. The other identity field is captured opportunistically when provided and valid (so a LinkedIn campaign can still record email when present).Deduplication semantics. Add is deduped both within the batch and against existing campaign leads. Identity is normalized before comparison — emails are lowercased; LinkedIn URLs drop trailing slashes and query strings. Duplicates silently fall out of the import count; the response separates imported from duplicates.Custom fields. custom_fields is a free-form JSONB record rendered as %custom_fields.<key>% in message templates. Use this for per-lead data the built-in columns don’t cover (industry, deal size, notes).Stats sync. Add and delete both recompute campaigns.stats atomically after the write via the recalculate_campaign_stats RPC — no manual stat refresh needed.Polling the list. status filters map to pipeline stages. pending is the launch queue; sent/connection_sent/connected/message_sent are in-flight; replied/bounced/completed/timed_out/cancelled are terminal. Use total from the response to drive pagination — with under 200 results per page and up to 200 allowed as limit, a single fetch often suffices.Scaling. Pre-query caps at 100k existing leads for dedup. Above that the DB unique constraint takes over — behavior is unchanged, just slower on write.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id
string
required

Campaign UUID

Query Parameters

page
integer
Required range: 1 <= x <= 9007199254740991
limit
integer
Required range: 1 <= x <= 200
status
string

Response

Page of leads with total count.

prospects
object[]
required
total
integer
required
Required range: 0 <= x <= 9007199254740991
page
integer
required
Required range: 0 < x <= 9007199254740991
limit
integer
required
Required range: 0 < x <= 9007199254740991