List contacts
GET/api/v1/contacts
curl -X GET 'https://www.unitpost.com/api/v1/contacts' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'User-Agent: my-app/1.0'{
"object": "list",
"has_more": false,
"data": [
{
"object": "contact",
"id": "id_123",
"email": "customer@example.com",
"phone": "string",
"first_name": "string",
"last_name": "string",
"unsubscribed": false,
"unsubscribed_at": "2026-01-01T00:00:00.000Z",
"unsubscribe_reason": "USER",
"custom_fields": {},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}
]
}Retrieve a list of the contacts in your workspace, newest-first and cursor-paginated. Each row includes the contact's core fields, its SMS number (phone) and any custom field values. Narrow the list with q (email, first or last name, and 3+ digits of a phone number), status, phone, segment_id (members of a segment; also requires segments:read) and, for a static segment, segment_subscription. A filter value it can't apply (a typo, an unknown id) is ignored and named in the Unitpost-Warning header, and the answer is the one without it; send Unitpost-Strict: true to have it refused instead. Use a contact's id (or email) with Retrieve a contact for the full record, add contacts with Create a contact, or bring a list in bulk with Start an async contact import. Requires the contacts:read capability.
Parameters8 fields
| Field | Type | Description |
|---|---|---|
limit | integer · query | Max rows to return (default 20, max 100). |
after | string · query | Return rows after this id (forward paging). |
before | string · query | Return rows before this id (backward paging). |
q | string · query | Search email, first and last name (case-insensitive); with 3 or more digits it also matches the SMS number. At most 200 characters. |
status | string · query | `subscribed` or `unsubscribed`: the contact-level marketing opt-out. |
phone | string · query | `has`: contacts with an SMS number; `none`: without one. |
segment_id | string · query | Only members of this segment: a static segment's members, or the contacts a dynamic segment's filter matches. Also requires `segments:read` (without it, or for an unknown segment, the filter is ignored with a warning; refused under `Unitpost-Strict`). |
segment_subscription | string · query | With a static `segment_id`: `subscribed` or `opted_out` of that segment's sends. A dynamic segment has no per-segment opt-out (422). |
Response · 200 fields12 fields
| Field | Type | Description |
|---|---|---|
objectrequired | string | — |
idrequired | string | — |
emailrequired | string | null | — |
phone | string | null | — |
first_namerequired | string | null | — |
last_namerequired | string | null | — |
unsubscribedrequired | boolean | — |
unsubscribed_atrequired | string | null | — |
unsubscribe_reasonrequired | enum | null | — |
custom_fieldsrequired | object | — |
created_atrequired | string | — |
updated_atrequired | string | — |