Sign in

v1

latestOpenAPI 3.1.02026-07-2671538.5 KB
Contacts

Update a contact by ID

Update an existing contact identified by its unique id. Include one or more fields to change. Field updates and consent changes can be combined in a single request.

Mutable fields: first_name, last_name, email, phone_number, tags, custom_fields.

email and phone_number can only be set when the existing value is null. Once populated, they cannot be changed or cleared.

Consent fields: email_consent, sms_consent. Use these to subscribe, unsubscribe, or otherwise manage a contact's marketing consent.

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

Required scope: contacts_write

patch/contacts/{id}

Path parameters

idstring required

The contact's unique identifier (returned as id in contact responses).

Request body

first_namestring

Updated first name.

last_namestring

Updated last name.

emailstring email

Sets the contact's email address. Only allowed when the contact's current email is null; once populated, email is immutable.

phone_numberstring

Sets the contact's phone number in E.164 format. Only allowed when the contact's current phone_number is null; once populated, phone_number is immutable.

tagsstring[]

Replaces all existing tags.

custom_fieldsobject

Replaces all existing custom fields. Must be a flat key-value object.

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

Update the contact's email marketing consent. compliance_suppressed is read-only — any write to a compliance-suppressed contact returns 422.

For merchant-suppressed contacts, writing any consent value first unsuppresses, then applies the requested transition (e.g. subscribed unsuppresses then subscribes).

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

Update the contact's SMS marketing consent. pending is read-only. subscribed, single_opt_in, and unsubscribed require the contact to have a phone number. single_opt_in is idempotent when the contact is already in that state, and returns 422 from terminal states (pending, confirmed, or unsubscribed).

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

{
  "first_name": "Janet",
  "last_name": "Smith",
  "email": "janet@example.com",
  "phone_number": "+15551234567",
  "tags": [
    "vip",
    "wholesale"
  ],
  "custom_fields": {
    "loyalty_tier": "platinum"
  },
  "email_consent": "unsubscribed",
  "sms_consent": "unsubscribed"
}

Response

Contact updated 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"
  }
}