Skip to main content
The Privy API is currently in a closed alpha. If you’d like access, please email us at support@privy.com.
Your business may need API access enabled before OAuth tokens work against the API. If requests fail despite valid credentials, confirm with Support that API access is turned on for your account. The Privy API lets you manage your contact list programmatically. You can create, update, unsubscribe, and delete contacts — or retrieve your full list with filtering and pagination.

​
Base URL

All API requests use the following base URL: 
https://dashboard.privy.com/v1

​
Quick start

1

Create an OAuth application

Go to Settings > Apps in your Privy dashboard and create a new application to get a client ID and client secret. See Authentication for details.
2

Get an access token

Exchange your credentials for a bearer token:
curl -X POST "https://dashboard.privy.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
3

Make your first request

Use the access token to list your contacts:
curl -X GET "https://dashboard.privy.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
4

Check the response

You’ll receive a JSON response with your contact data and pagination info:
{
  "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
  }
}

​
What you can do

EndpointDescription
GET /v1/contactsList contacts with filtering and pagination
POST /v1/contactsCreate a new contact
PATCH /v1/contactsUpdate a contact’s name, tags, or custom fields
POST /v1/contacts/unsubscribeUnsubscribe a contact from all email marketing
DELETE /v1/contactsRemove a contact from your list

​
Next steps

Authentication

Set up OAuth credentials and learn about scopes.

Rate Limits

Understand request limits and how to handle them.

Errors

Learn about error codes and response format.