Contact lists

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.

Request

{
  "name": "Partner leads October",
  "groupName": "Partner",
  "contacts": [
    { "name": "Ada Lovelace", "phoneNumber": "+15550100" },
    { "name": "Grace Hopper", "phoneNumber": "+15550101", "metadata": { "company": "Acme", "email": "[email protected]" } }
  ]
}

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.

Response · 201 Created

{
  "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>.

Keep the returned id; every other call uses it. List names are not unique.

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.

Request

{ "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.

Response · 200 OK

{ "success": true, "id": 4821 }

Example with curl

BASE=https://api.migration.powerdialer.ai/api/public/v1
AUTH=(-H "Authorization: Bearer $API_KEY" -H "x-user-email: [email protected]")

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[@]}"

API Reference: contact lists

Full parameter and response schemas with a live playground.

Get started

Guides

Reference

Create a list

Update a list

Delete a list

Example with curl

API Reference: contact lists

​Create a list

​Update a list

​Delete a list

​Example with curl

API Reference: contact lists

Create a list

Update a list

Delete a list

Example with curl