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 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://api.privy.com/v1

​
Quick start

1

Get a token

The fastest way to get started is to create an API token from Settings > API Tokens in your Privy dashboard. See API Tokens for details.Alternatively, create an OAuth application under Settings > Apps to use the OAuth client credentials flow.
2

Make your first request

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

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

API Tokens

Generate a token and start making requests in minutes.

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.