Contacts

Update a contact by ID

Changed on Nov 5, 2026

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}

Request

Base URL
https://api.privy.com/v1
Auth
HTTP bearer

Path parameters

idstring required

The contact's unique identifier (returned as id in contact responses). Ids are opaque cus_-prefixed strings — a numeric id from a Privy dashboard URL is not a valid API id and will 404; list contacts, or look the contact up by ?email= or ?phone_number=, instead.

Headers

Privy-Account-Idstring

Target a subaccount instead of the main connected account. Pass a subaccount id from get_account's subaccounts list. Only direct subaccounts of the connected account are reachable — omit this for the main account itself.

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 this field on a compliance-suppressed contact returns 422. The contact's other fields, and its sms_consent, stay editable.

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, subscribed, 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",
    "email_consent_at": "2025-03-20T14:22:00Z",
    "phone_number": "+15551234567",
    "sms_consent": "subscribed",
    "sms_consent_at": "2025-03-20T14:22:00Z",
    "source": "csv",
    "source_type": "import",
    "imported": true,
    "import_ids": [
      "im_k2R5m8Q"
    ],
    "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"
  }
}

Changes

Nov 5, 2026cf0885e90d5a Revision changes
- warning
  added the new forbidden enum value to the / response property for the response status
- warning
  added the new forbidden enum value to the / response property for the response status
- warning
  added the new forbidden enum value to the / response property for the response status
- warning
  added the new forbidden enum value to the / response property for the response status
- warning
  added the new forbidden enum value to the / response property for the response status
- warning
  added the new segment_builder_required enum value to the / response property for the response status
- warning
  added the new segment_builder_required enum value to the / response property for the response status
- warning
  added the new segment_builder_required enum value to the / response property for the response status
- warning
  added the new segment_builder_required enum value to the / response property for the response status
- warning
  added the new segment_builder_required enum value to the / response property for the response status
Nov 3, 2026fe500ab59b3b Revision changes
- breaking
  the response property / became nullable for the status
- breaking
  the response property / became nullable for the status
- breaking
  the response property / became nullable for the status
- breaking
  the response property / became nullable for the status
- warning
  added the new api_access_required enum value to the / response property for the response status
- warning
  added the new api_access_required enum value to the / response property for the response status
- warning
  added the new api_access_required enum value to the / response property for the response status
- warning
  added the new api_access_required enum value to the / response property for the response status
- warning
  added the new api_access_required enum value to the / response property for the response status
- warning
  added the new contacts_not_ready enum value to the / response property for the response status
- warning
  added the new contacts_not_ready enum value to the / response property for the response status
- warning
  added the new contacts_not_ready enum value to the / response property for the response status
- warning
  added the new contacts_not_ready enum value to the / response property for the response status
- warning
  added the new contacts_not_ready enum value to the / response property for the response status
- warning
  added the new no_connected_store enum value to the / response property for the response status
- warning
  added the new no_connected_store enum value to the / response property for the response status
- warning
  added the new no_connected_store enum value to the / response property for the response status
- warning
  added the new no_connected_store enum value to the / response property for the response status
- warning
  added the new no_connected_store enum value to the / response property for the response status
- warning
  added the new paid_plan_required enum value to the / response property for the response status
- warning
  added the new paid_plan_required enum value to the / response property for the response status
- warning
  added the new paid_plan_required enum value to the / response property for the response status
- warning
  added the new paid_plan_required enum value to the / response property for the response status
- warning
  added the new paid_plan_required enum value to the / response property for the response status
- warning
  added the new store_unavailable enum value to the / response property for the response status
- warning
  added the new store_unavailable enum value to the / response property for the response status
- warning
  added the new store_unavailable enum value to the / response property for the response status
- warning
  added the new store_unavailable enum value to the / response property for the response status
- warning
  added the new store_unavailable enum value to the / response property for the response status
- info
  added the new optional header request parameter Privy-Account-Id
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status

Operation history