Skip to main content
PUT
/
v2
/
contacts
curl -X PUT "https://app.tracklysms.com/api/v2/contacts" \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155559876",
    "list_number": "+18005551234",
    "custom_fields": {
      "vip_status": "gold",
      "last_purchase": "2026-02-10"
    }
  }'

{
  "success": true,
  "list_contact_id": "665a1b2c3d4e5f6a7b8c9d0f",
  "custom_fields": {
    "first_name": "Jane",
    "source": "landing_page_v2",
    "vip_status": "gold",
    "last_purchase": "2026-02-10"
  }
}
Update the custom fields attached to a contact on a given sending list. By default, the provided fields are merged into the existing custom fields — existing keys not included in the request are preserved. Set merge_fields to false to replace the entire custom fields object.

​
Body Parameters

​
phone_number
string
required
Contact phone number in E.164 format (e.g., +14155559876).
​
list_number
string
required
Sending list phone number in E.164 format (e.g., +18005551234). Must be a list owned by your account.
​
custom_fields
object
required
Key-value pairs to set on the contact’s custom fields. Values can be strings, numbers, or booleans.
​
merge_fields
boolean
default:"true"
When true (default), the provided keys are merged into the existing custom fields — keys not included in the request are preserved. When false, the existing custom fields are entirely replaced with the provided object.

​
Response Fields

​
success
boolean
Whether the operation completed successfully.
​
list_contact_id
string
Unique identifier of the ListContact record that was updated.
​
custom_fields
object
The full custom fields object after the update.

​
Examples

curl -X PUT "https://app.tracklysms.com/api/v2/contacts" \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155559876",
    "list_number": "+18005551234",
    "custom_fields": {
      "vip_status": "gold",
      "last_purchase": "2026-02-10"
    }
  }'

{
  "success": true,
  "list_contact_id": "665a1b2c3d4e5f6a7b8c9d0f",
  "custom_fields": {
    "first_name": "Jane",
    "source": "landing_page_v2",
    "vip_status": "gold",
    "last_purchase": "2026-02-10"
  }
}

​
Error Codes

HTTP StatusError CodeDescription
400missing_phone_numberThe phone_number field was not provided.
400missing_list_numberThe list_number field was not provided.
400missing_custom_fieldsThe custom_fields field was not provided.
400invalid_custom_fieldsThe custom_fields field must be a JSON object.
400invalid_phoneThe phone_number is not a valid E.164 phone number.
400invalid_list_numberThe list_number is not a valid E.164 phone number.
400contact_not_foundNo contact exists with the given phone number.
400list_not_foundNo sending list with the given list_number exists for this account.
400list_contact_not_foundThe contact exists but is not on the specified list.

​
Next Steps

Importing Contacts

Bulk update contacts

Create Audience

Segment contacts into audiences