Contacts in a list

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

Request

{
  "contacts": [
    { "name": "Ada Lovelace", "phoneNumber": "+15550100", "additionalNumbers": ["+15550199"] },
    { "name": "Grace Hopper", "phoneNumber": "+15550101", "metadata": { "company": "Acme" } },
    { "phoneNumber": "+15550102" }
  ]
}

Response · 200 OK

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

To change a contact’s details, remove it by phone number and add it again.

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

Response · 200 OK

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

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

API Reference: contacts

Full schemas with a live playground.

Get started

Guides

Reference

Contact shape

Add contacts (batch)

Remove a contact

Example with curl

API Reference: contacts

​Contact shape

​Add contacts (batch)

​Remove a contact

​Example with curl

API Reference: contacts

Contact shape

Add contacts (batch)

Remove a contact

Example with curl