Skip to main content
POST
/
contacts
Create a contact
curl --request POST \
  --url https://api.privy.com/v1/contacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "jane@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "tags": [
    "new-contact"
  ],
  "email_consent": "subscribed"
}
'
{
  "data": {
    "id": "cus_x9y8z7w6v5u4t3s2",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "email_consent": "subscribed",
    "phone_number": null,
    "sms_consent": "never_subscribed",
    "tags": [
      "new-contact"
    ],
    "custom_fields": {},
    "created_at": "2025-04-01T12:00:00Z",
    "updated_at": "2025-04-01T12:00:00Z"
  }
}

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.

Authorizations

​
Authorization
string
header
required

Send either an API token or an OAuth access token as Authorization: Bearer <token>. See the Authentication page for details.

Body

application/json

At least one of email or phone_number is required.

Use email_consent and sms_consent to set the contact's marketing consent status at creation time.

​
email
string<email>

Contact's email address.

Example:

"jane@example.com"

​
phone_number
string

Contact's phone number in E.164 format.

Example:

"+15551234567"

​
first_name
string

Contact's first name.

Example:

"Jane"

​
last_name
string

Contact's last name.

Example:

"Doe"

​
tags
string[]

Tags to apply to the contact.

Example:
["vip", "repeat-buyer"]
​
custom_fields
object

Flat key-value pairs. Nested objects are not allowed.

Example:
{ "loyalty_tier": "gold" }
​
email_consent
enum<string>

Email marketing consent status. If not provided, defaults to never_subscribed. compliance_suppressed is read-only and cannot be set on create.

Available options:
subscribed,
unsubscribed,
never_subscribed,
suppressed
Example:

"subscribed"

​
sms_consent
enum<string>

SMS marketing consent status. pending is read-only and cannot be set. subscribed and single_opt_in require a valid phone_number from a supported country. Cannot be unsubscribed for new contacts (no existing consent to revoke).

Available options:
subscribed,
unsubscribed,
never_subscribed,
single_opt_in
Example:

"never_subscribed"

​
send_welcome_sms
boolean
default:true

When sms_consent is set to subscribed and the contact transitions to a confirmed SMS opt-in state, Privy sends a TCPA-required welcome SMS. Set to false to suppress this message when you have already collected consent outside of Privy.

Example:

false

Response

Contact created successfully.

​
data
object