Sign in

v1

latestOpenAPI 3.1.02026-07-2671538.5 KB
Contacts

Create a contact

Create a new contact. At least one of email or phone_number is required.

If a contact with the same email or phone number already exists, a 409 Conflict error is returned with the id of the existing contact in error.id. Use the Update a contact endpoint to modify existing contacts.

If a previously deleted contact matches the provided email or phone number, the contact is restored with the new data.

When sms_consent is subscribed, Privy automatically sends a TCPA-required welcome SMS to the contact. Pass send_welcome_sms: false to suppress this message if you have already collected consent outside of Privy.

Required scope: contacts_write

post/contacts

Request body

emailstring email

Contact's email address.

phone_numberstring

Contact's phone number in E.164 format.

first_namestring

Contact's first name.

last_namestring

Contact's last name.

tagsstring[]

Tags to apply to the contact.

custom_fieldsobject

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

email_consent'subscribed' | 'unsubscribed' | 'never_subscribed' | 'suppressed'

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

sms_consent'subscribed' | 'unsubscribed' | 'never_subscribed' | 'single_opt_in'

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

send_welcome_smsboolean

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 request

{
  "email": "jane@example.com",
  "phone_number": "+15551234567",
  "first_name": "Jane",
  "last_name": "Doe",
  "tags": [
    "vip",
    "repeat-buyer"
  ],
  "custom_fields": {
    "loyalty_tier": "gold"
  },
  "email_consent": "subscribed",
  "sms_consent": "never_subscribed"
}

Response

Contact created successfully.

Example response

{
  "data": {
    "id": "cus_a1b2c3d4e5f6g7h8",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "email_consent": "subscribed",
    "phone_number": "+15551234567",
    "sms_consent": "subscribed",
    "tags": [
      "vip",
      "repeat-buyer"
    ],
    "custom_fields": {
      "loyalty_tier": "gold",
      "referral_code": "JANE2024"
    },
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-03-20T14:22:00Z"
  }
}