Skip to main content

Documentation Index

Fetch the complete documentation index at: https://help.privy.com/llms.txt

Use this file to discover all available pages before exploring further.

The Privy API is available to approved accounts. 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 your bearer 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": [
    {
      "id": "cus_a1b2c3d4e5f6g7h8",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "email_permission": "subscribed",
      "phone_number": "+15551234567",
      "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
GET /v1/contacts/{id}Get a single contact by ID
POST /v1/contactsCreate a new contact
PATCH /v1/contacts/{id}Update a contact by ID
POST /v1/contacts/{id}/unsubscribeUnsubscribe a contact from all email marketing
DELETE /v1/contacts/{id}Delete a contact by ID

​
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.