Overview
A lead is a contact record, a person your team is reaching out to. Leads live inside lead lists, which are collections used to organize contacts and enroll them into campaigns. Every lead has:- Core identity fields (
first_name,last_name,email,phone_number,linkedin_url,company,title) - Enrichment fields (
company_domain,industry,city,country, and more) - Status fields (
status,pipeline_stage,traffic_light_status,automation_paused) - Tags and a full activity timeline (calls, emails, SMS, LinkedIn, WhatsApp messages)
Creating leads
A lead always goes into a lead list, so sendlead_list_id.
rows to import many leads at once, or search_id to import chosen results of a prospect search. See Imports and prospecting.
Listing and getting leads
One endpoint lists leads and returns a single lead.pipeline_stage values: new, contacted, engaged, meeting_booked, meeting_scheduled, proposal_sent, closed_won, closed_lost
Valid status values: active, unsubscribed, bounced, dnc
Results are paginated. Use page and per_page to navigate:
The response envelope includes
total so you can calculate the number of pages: Math.ceil(total / per_page).
Updating a lead
PATCH /api/v1/public/leads/{lead_id} changes fields, the pipeline stage, tags and the traffic light in one call. Send only what you want to change.
applied. The response is the updated lead with its tags. See Lead tags.
Moving a lead’s stage here is the same action that moves it through the visual pipeline in the dashboard.
Lead pipeline
Every lead moves through a sales pipeline. Stages advance automatically during campaign execution or can be set manually via the API.Enriching, verifying and researching leads
POST /api/v1/public/leads/enrich does three jobs. Pick them with actions, and say which leads with lead_ids or a whole lead_list_id.
The response has one entry per action under
results. Each action reports on its own, so one failing does not hide the others:
method: "database", enrichment tries the workspace’s connected services in order and stops at the first match. A workspace with none connected answers no_providers; use web_search instead. A web search that takes too long answers reason: "timed_out".
Send an Idempotency-Key header with verify_email so a retry is charged once.
Lead activity timeline
Addinclude=activities when you get one lead to receive its history, newest first:
activities is an array of events:
Lead lists
Organize leads into lists for bulk operations. See Lead lists. To enrich a whole list, send itslead_list_id to POST /leads/enrich.
DNC and unsubscribes
Leads withstatus: "dnc" or status: "unsubscribed" are never contacted. You can also manage the DNC list directly, see the DNC guide.