Contacts

List contacts

Changed on Nov 5, 2026

Retrieve a paginated list of contacts, most recently created first. Optionally filter by email, phone number, or consent status.

Unfiltered, the list covers every contact in the account whatever their consent state, so pagination.total_count is the size of your contact list — not the size of your mailable or textable audience. Filter on email_consent=subscribed or sms_consent=subscribed for those. Contacts you have deleted are excluded — but deletion is soft: creating a contact with the same email or phone number restores the existing record rather than creating a new one, so a previously deleted contact can reappear here later with its original id and history.

Required scope: contacts_read

get/contacts

Request

Base URL
https://api.privy.com/v1
Auth
HTTP bearer

Query parameters

pageinteger

Page number (starts at 1).

per_pageinteger

Number of results per page. Values outside 10–100 are clamped to the nearest bound.

emailstring email

Filter by exact email address.

phone_numberstring

Filter by exact phone number (E.164 format).

email_consent'subscribed' | 'unsubscribed' | 'never_subscribed' | 'suppressed' | 'compliance_suppressed'

Filter by email consent status. subscribed matches both explicit and implicit opt-in. suppressed matches merchant-suppressed contacts only; compliance_suppressed matches system/compliance-suppressed contacts.

sms_consent'subscribed' | 'unsubscribed' | 'never_subscribed' | 'single_opt_in' | 'pending'

Filter by SMS consent status.

created_afterstring date-time

Only contacts created strictly after this ISO 8601 datetime (or date). Zone-less datetimes are interpreted as UTC; bare dates as midnight US Eastern time.

created_beforestring date-time

Only contacts created strictly before this ISO 8601 datetime (or date). Zone-less datetimes are interpreted as UTC; bare dates as midnight US Eastern time.

updated_afterstring date-time

Only contacts updated strictly after this ISO 8601 datetime (or date). Zone-less datetimes are interpreted as UTC; bare dates as midnight US Eastern time.

updated_beforestring date-time

Only contacts updated strictly before this ISO 8601 datetime (or date). Zone-less datetimes are interpreted as UTC; bare dates as midnight US Eastern time.

import_idstring

Only contacts touched by this import — including contacts that already existed before it ran. Takes an email import id (im_…) from a contact's import_ids. Unknown or malformed ids return a 422; SMS consent imports (sim_…) do not link to contacts.

Headers

Privy-Account-Idstring

Target a subaccount instead of the main connected account. Pass a subaccount id from get_account's subaccounts list. Only direct subaccounts of the connected account are reachable — omit this for the main account itself.

Response

A paginated list of contacts.

Example response

{
  "data": [
    {
      "id": "cus_a1b2c3d4e5f6g7h8",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "email_consent": "subscribed",
      "email_consent_at": "2025-03-20T14:22:00Z",
      "phone_number": "+15551234567",
      "sms_consent": "subscribed",
      "sms_consent_at": "2025-03-20T14:22:00Z",
      "source": "csv",
      "source_type": "import",
      "imported": true,
      "import_ids": [
        "im_k2R5m8Q"
      ],
      "tags": [
        "vip",
        "repeat-buyer"
      ],
      "custom_fields": {
        "loyalty_tier": "gold",
        "referral_code": "JANE2024"
      },
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-03-20T14:22:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_count": 142,
    "total_pages": 6
  }
}

Changes

Nov 5, 2026cf0885e90d5a Revision changes
- warning
  added the new forbidden enum value to the / response property for the response status
- warning
  added the new forbidden enum value to the / response property for the response status
- warning
  added the new forbidden enum value to the / response property for the response status
- warning
  added the new forbidden enum value to the / response property for the response status
- warning
  added the new forbidden enum value to the / response property for the response status
- warning
  added the new segment_builder_required enum value to the / response property for the response status
- warning
  added the new segment_builder_required enum value to the / response property for the response status
- warning
  added the new segment_builder_required enum value to the / response property for the response status
- warning
  added the new segment_builder_required enum value to the / response property for the response status
- warning
  added the new segment_builder_required enum value to the / response property for the response status
Nov 3, 2026fe500ab59b3b Revision changes
- breaking
  for the query request parameter per_page, default value was changed from 25 to 40
- breaking
  for the query request parameter per_page, the min was increased from 1.00 to 10.00
- breaking
  the response property // became nullable for the status
- breaking
  the response property // became nullable for the status
- breaking
  the response property // became nullable for the status
- breaking
  the response property // became nullable for the status
- warning
  added the new api_access_required enum value to the / response property for the response status
- warning
  added the new api_access_required enum value to the / response property for the response status
- warning
  added the new api_access_required enum value to the / response property for the response status
- warning
  added the new api_access_required enum value to the / response property for the response status
- warning
  added the new contacts_not_ready enum value to the / response property for the response status
- warning
  added the new contacts_not_ready enum value to the / response property for the response status
- warning
  added the new contacts_not_ready enum value to the / response property for the response status
- warning
  added the new contacts_not_ready enum value to the / response property for the response status
- warning
  added the new no_connected_store enum value to the / response property for the response status
- warning
  added the new no_connected_store enum value to the / response property for the response status
- warning
  added the new no_connected_store enum value to the / response property for the response status
- warning
  added the new no_connected_store enum value to the / response property for the response status
- warning
  added the new paid_plan_required enum value to the / response property for the response status
- warning
  added the new paid_plan_required enum value to the / response property for the response status
- warning
  added the new paid_plan_required enum value to the / response property for the response status
- warning
  added the new paid_plan_required enum value to the / response property for the response status
- warning
  added the new store_unavailable enum value to the / response property for the response status
- warning
  added the new store_unavailable enum value to the / response property for the response status
- warning
  added the new store_unavailable enum value to the / response property for the response status
- warning
  added the new store_unavailable enum value to the / response property for the response status
- info
  added the new optional header request parameter Privy-Account-Id
- info
  added the new optional query request parameter created_after
- info
  added the new optional query request parameter created_before
- info
  added the new optional query request parameter import_id
- info
  added the new optional query request parameter updated_after
- info
  added the new optional query request parameter updated_before
- info
  added the non-success response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status

Operation history