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

# Create Lead List

> Create a lead list in your Tuco workspace, optionally seeding it with contacts. Returns the listId used by the leads and availability endpoints.

<Note>
  A **list** owns leads. `listId` is what you pass to
  [`POST /api/leads`](/api-reference/endpoint/create) to file new leads somewhere specific, and to
  [`POST /api/leads/check-availability`](/api-reference/endpoint/bulk-check-availability) to check a
  whole list at once. These endpoints are how you get a `listId` without opening the dashboard.
</Note>

Creates an empty list, or creates one and fills it in the same call by passing `contacts`.

## Authentication

Pass your workspace API key as a Bearer token, or use a Clerk session token.

```bash theme={null}
Authorization: Bearer tuco_xxxxxxxxxxxxx
```

***

## Request body

<ParamField body="name" type="string" required>
  List name. **Must be unique in the workspace** — a duplicate returns
  `400 List name already exists` with `code: "NAME_EXISTS"`. A missing or non-string name returns
  `400` with `code: "NAME_REQUIRED"`.
</ParamField>

<ParamField body="description" type="string">
  Optional description.
</ParamField>

<ParamField body="contacts" type="object[]">
  Optional. Seed the list with leads in the same call. Same per-lead shape as
  [`POST /api/leads`](/api-reference/endpoint/create) — `firstName`, `lastName`, `phone`, `email`,
  `companyName`, `customFields`, and so on. Prefer `phone` in E.164 as the identifier.

  When present, the response is the **import** shape (`listId`, `savedCount`, `duplicateCount`)
  rather than the list object.
</ParamField>

<ParamField body="source" type="string" default="api">
  Origin label stored on the created leads, e.g. `"api"` or `"gohighlevel"`. Only used with `contacts`.
</ParamField>

<ParamField body="ghlLocationId" type="string">
  GoHighLevel location id, stored on the created leads. Only applied when `source` is `"gohighlevel"`.
</ParamField>

***

## Example — empty list

```bash theme={null}
curl -X POST "https://app.tuco.ai/api/lists" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Q4 outbound", "description": "Sourced from the October webinar" }'
```

### Success (`200 OK`)

```json theme={null}
{
  "message": "List created successfully",
  "list": {
    "_id": "6ac3f1a271adb32c88d566f1",
    "name": "Q4 outbound",
    "description": "Sourced from the October webinar",
    "workspaceId": "org_3CzFir0Fps4hHL4nbU9WQ6FR4ur",
    "leadCount": 0,
    "createdAt": "2026-10-05T19:02:10.004Z",
    "updatedAt": "2026-10-05T19:02:10.004Z"
  }
}
```

## Example — create and seed in one call

```bash theme={null}
curl -X POST "https://app.tuco.ai/api/lists" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q4 outbound",
    "contacts": [
      { "firstName": "Jane", "lastName": "Doe", "phone": "+14155551234" }
    ]
  }'
```

### Success (`200 OK`)

```json theme={null}
{
  "listId": "6ac3f1a271adb32c88d566f1",
  "savedCount": 1,
  "duplicateCount": 0
}
```

<Note>
  Take `listId` from either response shape and pass it to
  [`POST /api/leads`](/api-reference/endpoint/create) to add more leads later.
</Note>

***

## Errors

| Status | When | Body |
| - | - | - |
| `400` | `name` missing or not a string | `{ "error": "List name is required", "code": "NAME_REQUIRED" }` |
| `400` | A list with that name already exists | `{ "error": "List name already exists", "code": "NAME_EXISTS" }` |
| `400` | A contact row is invalid | `{ "error": "...", "code": "INVALID_LEADS" }` |
| `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` |
| `402` | Subscription past due (workspace read-only) | `{ "error": "READ_ONLY", "code": "READ_ONLY", "reason": "past_due" }` |
| `429` | More than 120 requests/min for this workspace | `{ "error": "Rate limit exceeded" }` |


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