/ Docs
API ReferenceContacts

Update a Contact

Page Tools
PATCH/contacts/{identifier}

Partial update. Scalars: send a value to set it, null to clear it, omit to leave untouched. tags replaces the whole list; customFields merges per key (null deletes a key). phoneNumber is immutable. Set active=true to restore an archived contact.

Authenticate with your brand’s x-api-key.Authentication

Path Parameters

identifierstringrequired

Contact id (uuid) or phone number (digits-only recommended in URLs; E.164 requires encoding + as %2B)

Request Body

application/json
  • At least 1 properties
  • No additional properties
firstNamestring · nullable
  • 1–255 characters
lastNamestring · nullable
  • 1–255 characters
emailstring · nullable
  • Up to 255 characters
  • Format: email
statestring · nullable
  • 1–255 characters
countrystring · nullable
  • 1–255 characters
dobstring · nullable

Date of birth in YYYY-MM-DD format. Must be a valid date in the past; null clears the value.

  • Pattern: ^\d{4}-\d{2}-\d{2}$
genderstring · nullable
  • 1–255 characters
preferredLanguagestring · nullable
  • 1–255 characters
tagsarray of string

Full replace on updates; usable in segment rules

  • Up to 100 items
Show item detailsHide item details for body.tags

Each item

  • 1–100 characters
string
  • 1–100 characters
customFieldsobject

Map of up to 50 fields. Values may be strings (up to 1,000 characters), numbers, booleans, arrays of up to 100 strings, or null. Nested objects are not accepted. Keys must match ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$; __proto__, constructor, and prototype are reserved. A null value deletes that key on update.

  • Up to 50 properties
Show child fieldsHide child fields for body.customFields
[key]multiple types
Show child fieldsHide child fields for body.customFields.[key]

One or more variants may apply.

string · nullable
  • Up to 1000 characters
marketingConsentstring

Setting OPTED_IN attests that you collected the contact's marketing consent. OPTED_IN is rejected (422) when the contact previously opted out (e.g. texted STOP); OPTED_OUT is always accepted. Contacts default to UNKNOWN, and campaigns only send to OPTED_IN contacts.

Allowed values"OPTED_IN""OPTED_OUT"
activeboolean

Set true to restore an archived contact

Responses

The updated contact

idstringrequired
phoneNumberstringrequired

Always returned in E.164 format

activebooleanrequired

false when the contact has been archived (DELETE)

firstNamestring · nullablerequired
lastNamestring · nullablerequired
emailstring · nullablerequired
statestring · nullablerequired
countrystring · nullablerequired
dobstring · nullablerequired

Date of birth (YYYY-MM-DD)

genderstring · nullablerequired
preferredLanguagestring · nullablerequired
tagsarray of stringrequired
Show item detailsHide item details for response-200.tags

Each item

string
customFieldsobjectrequired

Stored custom-field values keyed by field name. See create/update request schemas for accepted write types and limits.

Show child fieldsHide child fields for response-200.customFields
[key]any

Additional keys may contain any JSON value.

marketingConsentobjectrequired
Show child fieldsHide child fields for response-200.marketingConsent
channelstringrequired
Allowed values"MOBILE"
statusstringrequired

Campaigns are only sent to OPTED_IN contacts. Contacts created via the API start as UNKNOWN until consent is set.

Allowed values"UNKNOWN""SENT""OPTED_IN""OPTED_OUT"
updatedAtstring · nullablerequired
createdAtstringrequired
updatedAtstringrequired

Get a Contact

GET /contacts/{identifier}

Archive a Contact

DELETE /contacts/{identifier}