> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendora.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Lead lists

> Group leads for repeatable enrichment, campaign enrollment, and reporting workflows.

## 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

```bash theme={"dark"}
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

```bash theme={"dark"}
# 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:

```bash theme={"dark"}
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:

```bash theme={"dark"}
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](/guides/leads) 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:

```bash theme={"dark"}
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](/guides/jobs) until the job reaches `completed`, `failed`, or `cancelled`.

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

## Use a list in a campaign

Campaign enrollment accepts a list ID for bulk enrollment:

```bash theme={"dark"}
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](/guides/campaigns) for individual-lead enrollment, preflight checks, and launch controls.

## Delete a list

```bash theme={"dark"}
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](/guides/leads) when that is the intended operation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.