---
title: "List contacts"
method: GET
path: "/contacts"
tags: ["Contacts"]
---

# List contacts

`GET /contacts`

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

**Required scope:** `contacts_read`

## Query parameters

- `page` integer
- `per_page` integer
- `email` string, email
- `phone_number` string
- `email_consent` 'subscribed' | 'unsubscribed' | 'never_subscribed' | 'suppressed' | 'compliance_suppressed'
- `sms_consent` 'subscribed' | 'unsubscribed' | 'never_subscribed' | 'single_opt_in' | 'pending'

## Response `200`

A paginated list of contacts.

- object
  - `data` Contact[]
    - `id` string — Stable, unique identifier for the contact. Use this value in `/v1/contacts/{id}` endpoints.
    - `first_name` string
    - `last_name` string
    - `email` string, email
    - `email_consent` 'subscribed' | 'unsubscribed' | 'never_subscribed' | 'suppressed' | 'compliance_suppressed' — Email marketing consent status. - `subscribed` — contact opted into email (explicit or implicit consent). - `unsubscribed` — contact opted out of email. - `never_subscribed` — no opt-in and no opt-out. - `suppressed` — merchant-suppressed (bounce list, manual action). - `compliance_suppressed` — system-suppressed (CAN-SPAM, abuse complaint). Read-only.
    - `phone_number` string
    - `sms_consent` 'subscribed' | 'unsubscribed' | 'never_subscribed' | 'single_opt_in' | 'pending' — SMS marketing consent status. - `subscribed` — contact has confirmed SMS opt-in. - `unsubscribed` — contact opted out of SMS. - `never_subscribed` — no opt-in and no opt-out. - `single_opt_in` — merchant collected a single opt-in (not yet confirmed). - `pending` — Privy is awaiting a confirmation reply. Read-only.
    - `tags` string[]
    - `custom_fields` object
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - `pagination` PaginationEnvelope
    - `page` integer
    - `per_page` integer
    - `total_count` integer
    - `total_pages` integer

## Other responses

- `401` — Missing or invalid bearer token.
- `403` — Token lacks the required scope for this endpoint.
- `422` — One or more fields failed validation.
- `429` — Rate limit exceeded. Retry after the specified time.

---

[API](https://skmtc.dev/privy/apis/privy-api.md) · [All operations](https://skmtc.dev/privy/apis/privy-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/privy/privy-api/revisions/5378aff56b9a/schema)