Skip to main content

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)
Five endpoints cover leads: List or get leads, Create leads, Update lead, Delete lead, and Enrich, verify or research leads.

Creating leads

A lead always goes into a lead list, so send lead_list_id.
The same endpoint also takes 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.
Valid 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).
All Sendora write operations are idempotent, submitting the same request twice produces the same result without side effects. Enrolling a lead who is already in a campaign returns skipped: 1 rather than an error. Safe to retry on network failures.

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.
The steps run in this order: fields and stage, tags added, tags removed, traffic light. If one fails, the steps before it stay applied and the error lists them under 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:
With 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

Add include=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 its lead_list_id to POST /leads/enrich.

DNC and unsubscribes

Leads with status: "dnc" or status: "unsubscribed" are never contacted. You can also manage the DNC list directly, see the DNC guide.