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

# Contacts in a list

> Add contacts in batches of up to 10,000, and remove them by id or phone number.

Add contacts in batches of up to 10,000 per request, and remove one contact at a time by id or by phone number.

## Contact shape

| Field | Type | Notes |
| - | - | - |
| `phoneNumber` | string, 1–50 chars | **Required.** Send in E.164 form (`+15550100`) so dialing and matching work. |
| `name` | string, up to 500 chars | Optional. Empty if omitted. |
| `additionalNumbers` | array of strings, up to 10 | Optional alternate numbers for the same person. |
| `metadata` | object | Optional free-form fields shown on the contact — company, email, title, anything your system has. |

Unknown top-level fields are rejected with `400`.

## Add contacts (batch)

`POST /contact-lists/{id}/contacts`

```json Request theme={null}
{
  "contacts": [
    { "name": "Ada Lovelace", "phoneNumber": "+15550100", "additionalNumbers": ["+15550199"] },
    { "name": "Grace Hopper", "phoneNumber": "+15550101", "metadata": { "company": "Acme" } },
    { "phoneNumber": "+15550102" }
  ]
}
```

```json Response · 200 OK theme={null}
{
  "contactListId": 4821,
  "received": 3,
  "added": 2,
  "skippedExisting": 1,
  "duplicatesInPayload": 0
}
```

The add is **append-only**:

* A phone number already in the list is skipped and counted in `skippedExisting`; its name or metadata is **not** updated.
* Repeated numbers inside one payload collapse to the first one and are counted in `duplicatesInPayload`.
* The whole batch is written in one transaction, so a failure leaves nothing half-applied and the request can simply be retried.

<Tip>To change a contact's details, remove it by phone number and add it again.</Tip>

## Remove a contact

By contact id:

`DELETE /contact-lists/{id}/contacts/{contactId}`

By phone number (URL-encode the `+` as `%2B`):

`DELETE /contact-lists/{id}/contacts?phoneNumber=%2B15550100`

The phone-number form removes every contact in that list whose primary **or** additional number matches, with or without the leading `+`.

```json Response · 200 OK theme={null}
{ "contactListId": 4821, "removed": 1 }
```

A number or id that is not in the list answers `404 {"error":"Contact not found in this list"}`. Removing deletes the contact record, the same as deleting a contact in the app.

## Example with curl

```bash theme={null}
curl -X POST "$BASE/contact-lists/4821/contacts" "${AUTH[@]}" -H "Content-Type: application/json" \
  -d '{"contacts":[{"name":"Grace Hopper","phoneNumber":"+15550101","metadata":{"company":"Acme"}}]}'

curl -X DELETE "$BASE/contact-lists/4821/contacts?phoneNumber=%2B15550101" "${AUTH[@]}"
```

<Card title="API Reference: contacts" icon="code" href="/api-reference/add-contacts">
  Full schemas with a live playground.
</Card>


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