Skip to main content
GET
/
v1
/
contacts
List contacts
curl --request GET \
  --url https://api.privy.com/v1/v1/contacts \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "email_permission": "subscribed",
      "phone_number": "+15551234567",
      "contact_phone_permission": "subscribed",
      "tags": [
        "vip"
      ],
      "custom_fields": {
        "loyalty_tier": "gold"
      },
      "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
  }
}

Authorizations

​
Authorization
string
header
required

OAuth 2.0 client credentials flow. Exchange your client ID and client secret for an access token at the token URL, then include it as Authorization: Bearer <token>. See the Authentication page for details.

Query Parameters

​
page
integer
default:1

Page number (starts at 1).

Required range: x >= 1
​
per_page
integer
default:25

Number of results per page.

Required range: 1 <= x <= 100
​
email
string<email>

Filter by exact email address.

​
phone_number
string

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

​
email_permission
enum<string>

Filter by email consent status.

Available options:
subscribed,
unsubscribed,
non_subscribed
​
contact_phone_permission
string

Filter by SMS consent status.

Response

A paginated list of contacts.

​
data
object[]
​
pagination
object