Lead lists

Overview

A lead list is a reusable collection of leads in your workspace. Lists are useful when the same audience needs to be enriched, enrolled, or reported on more than once. A lead can belong to more than one list. The Lead Lists API supports:

Creating and maintaining named lists
Adding leads directly to a list
Listing the leads in a list
Enriching every lead in a list asynchronously
Deleting a list without deleting the underlying leads

Create a list

curl -X POST https://api.sendora.ai/api/v1/public/lead-lists \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q3 operations leaders",
    "description": "Operations leaders at our target accounts"
  }'

Save the returned id; it is used by the remaining list endpoints.

List and update lists

# List workspace lists
curl "https://api.sendora.ai/api/v1/public/lead-lists" \
  -H "X-API-Key: sk_live_..."

# Fetch one list and its metadata
curl "https://api.sendora.ai/api/v1/public/lead-lists/{list_id}" \
  -H "X-API-Key: sk_live_..."

# Rename or describe a list
curl -X PATCH "https://api.sendora.ai/api/v1/public/lead-lists/{list_id}" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Q3 operations and revenue leaders" }'

Updating a list changes list metadata only. It does not change the leads already assigned to it.

Add and list leads

Create a lead inside a list with the list-specific endpoint:

curl -X POST "https://api.sendora.ai/api/v1/public/lead-lists/{list_id}/leads" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@acme.com",
    "company": "Acme Corp",
    "title": "COO"
  }'

List the leads currently in a list:

curl "https://api.sendora.ai/api/v1/public/lead-lists/{list_id}/leads?page=1&per_page=50" \
  -H "X-API-Key: sk_live_..."

Use the general Leads guide when you need to update, enrich, or inspect an individual lead after it has been added.

Enrich a list

Enrichment runs in the background so large lists do not block the request:

curl -X POST "https://api.sendora.ai/api/v1/public/lead-lists/{list_id}/enrich" \
  -H "X-API-Key: sk_live_..."

The response includes a job_id. Poll Jobs until the job reaches completed, failed, or cancelled.

Enrichment can update lead fields and consume workspace enrichment credits. Start with a small list when validating a new enrichment workflow.

Use a list in a campaign

Campaign enrollment accepts a list ID for bulk enrollment:

curl -X POST "https://api.sendora.ai/api/v1/public/campaigns/{campaign_id}/leads" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "lead_list_id": "<list_id>" }'

See Campaigns for individual-lead enrollment, preflight checks, and launch controls.

Delete a list

curl -X DELETE "https://api.sendora.ai/api/v1/public/lead-lists/{list_id}" \
  -H "X-API-Key: sk_live_..."

Deleting a list removes the grouping, not the leads inside it. Delete individual leads through the Leads API when that is the intended operation.

Getting Started

Guides

Overview

Create a list

List and update lists

Add and list leads

Enrich a list

Use a list in a campaign

Delete a list

​Overview

​Create a list

​List and update lists

​Add and list leads

​Enrich a list

​Use a list in a campaign

​Delete a list

Overview

Create a list

List and update lists

Add and list leads

Enrich a list

Use a list in a campaign

Delete a list