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

# Contact lists

> Create, update and delete the lists reps dial from.

Three calls manage a list itself: create, update, delete. A list belongs to the acting user. A list that exists but belongs to someone else answers `404`, the same as a missing list.

## Create a list

`POST /contact-lists`

Creates a list, optionally seeded with contacts in the same call. Contacts go through the same path as a CSV upload, including background enrichment.

```json Request theme={null}
{
  "name": "Partner leads October",
  "groupName": "Partner",
  "contacts": [
    { "name": "Ada Lovelace", "phoneNumber": "+15550100" },
    { "name": "Grace Hopper", "phoneNumber": "+15550101", "metadata": { "company": "Acme", "email": "grace@acme.com" } }
  ]
}
```

| Field | Type | Notes |
| - | - | - |
| `name` | string, 1–150 chars | **Required.** Shown in the app. |
| `groupName` | string up to 100 chars, or `null` | Optional folder-style grouping. |
| `contacts` | array, 1–10,000 items | Optional. Omit for an empty list. Same shape as [batch add](/guides/contacts#add-contacts-batch). |

```json Response · 201 Created theme={null}
{
  "id": 4821,
  "name": "Partner leads October",
  "groupName": "Partner",
  "contactsCount": 2,
  "orgId": "org_2xyz...",
  "createdAt": "2026-10-06T12:00:00.000Z",
  "updatedAt": "2026-10-06T12:00:00.000Z"
}
```

If the payload repeats a phone number, only the first occurrence is kept and the response adds `"duplicatesInPayload": <n>`.

<Tip>Keep the returned `id`; every other call uses it. List names are not unique.</Tip>

## Update a list

`PATCH /contact-lists/{id}`

Renames the list and/or changes its group. Send at least one field. `"groupName": null` clears the group.

```json Request theme={null}
{ "name": "Partner leads Q4", "groupName": null }
```

Response `200 OK` with the same list object as create.

## Delete a list

`DELETE /contact-lists/{id}`

Deletes the list **and the contacts in it**, exactly as deleting in the app does. No body.

```json Response · 200 OK theme={null}
{ "success": true, "id": 4821 }
```

## Example with curl

```bash theme={null}
BASE=https://api.migration.powerdialer.ai/api/public/v1
AUTH=(-H "Authorization: Bearer $API_KEY" -H "x-user-email: rep@company.com")

curl -X POST "$BASE/contact-lists" "${AUTH[@]}" -H "Content-Type: application/json" \
  -d '{"name":"Partner leads October","contacts":[{"name":"Ada Lovelace","phoneNumber":"+15550100"}]}'

curl -X PATCH "$BASE/contact-lists/4821" "${AUTH[@]}" -H "Content-Type: application/json" \
  -d '{"name":"Partner leads Q4"}'

curl -X DELETE "$BASE/contact-lists/4821" "${AUTH[@]}"
```

<Card title="API Reference: contact lists" icon="code" href="/api-reference/create-contact-list">
  Full parameter and response schemas with a live playground.
</Card>


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