# Contacts API

Canonical: https://tyxter.com/docs/api-reference/contacts
Section: API reference

Contacts, consent, bulk import, data export, and erasure endpoints.

# Contacts API

Public contact endpoints cover opt-in, opt-out, list, bulk import, data export, and erasure.

`POST /v1/contacts/bulk-import` accepts `{ rows, source? }`, with 1–1,000 rows. Each row requires
an E.164 `phone` and may include `metadata`; `source` defaults to `api`. Repeated phones in one
payload are collapsed. The response returns every contact from the deduplicated input in `data`,
plus `imported` for newly opted-in contacts and `skipped` for contacts already opted in. Reuse the
same `Idempotency-Key` only when retrying an identical import.

For opt-out imports, call `POST /v1/contacts/opt-out` per phone with `contacts:write` and
an `Idempotency-Key`. The shared source-IP admission ceiling is 10 requests/second,
with a 60-request API-origin burst capacity; other routes and edge limits can also
consume or restrict traffic. Use one request at a time, initially two/second, honor
`Retry-After` on 429, retry the identical body/key, and stop visibly after bounded retries.
See the [runnable opt-out import example](/contacts#import-an-opt-out-list).
The bulk-import endpoint opts contacts in; never use it for a suppression list.