Skip to main content
POST
/
v1
/
contacts
Create a contact
curl --request POST \
  --url https://api.privy.com/v1/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": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "email_permission": "subscribed",
    "phone_number": null,
    "contact_phone_permission": "non_subscribed",
    "tags": [
      "new-contact"
    ],
    "custom_fields": {},
    "created_at": "2025-04-01T12:00:00Z",
    "updated_at": "2025-04-01T12:00:00Z"
  }
}

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.

Body

application/json

At least one of email or phone_number is required.

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

Available options:
subscribed,
unsubscribed,
non_subscribed
Example:

"subscribed"

​
sms_consent
enum<string>

SMS marketing consent status. Setting to subscribed requires a valid phone_number from a supported country. Cannot be unsubscribed for new contacts.

Available options:
subscribed,
unsubscribed,
non_subscribed
Example:

"non_subscribed"

Response

Contact created successfully.

​
data
object