List contacts

List contacts

GET/api/v1/contacts

GET /contacts
curl -X GET 'https://www.unitpost.com/api/v1/contacts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "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
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
qstring · querySearch email, first and last name (case-insensitive); with 3 or more digits it also matches the SMS number. At most 200 characters.
statusstring · query`subscribed` or `unsubscribed`: the contact-level marketing opt-out.
phonestring · query`has`: contacts with an SMS number; `none`: without one.
segment_idstring · queryOnly 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_subscriptionstring · queryWith 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
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
emailrequiredstring | null—
phonestring | null—
first_namerequiredstring | null—
last_namerequiredstring | null—
unsubscribedrequiredboolean—
unsubscribed_atrequiredstring | null—
unsubscribe_reasonrequiredenum | null—
custom_fieldsrequiredobject—
created_atrequiredstring—
updated_atrequiredstring—
200401403404422503

Search docs and guides

Search the docs and product guides.