Contacts

Create a contact

Changed on Nov 5, 2026

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

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

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

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",
    "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 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 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 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
- 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