Skip to main content
You can update any contact field after creation. The v1 endpoint identifies the contact by its integer ID, and the v2 endpoint uses a UUID. Custom fields can be merged into existing values or fully overwritten using the overwrite query parameter.

​
PUT /v1/contact/

Updates a contact by integer ID.

​
Path parameters

​
id
integer
required
The integer ID of the contact to update.

​
Query parameters

​
overwrite
boolean
default:"false"
When true, replaces all custom field values with the values you provide, removing any fields not included in the request. When false (the default), merges your values into the existing custom fields.

​
Request body

​
phone
string
required
The contact’s phone number in E.164 format without the leading +.
​
first
string
The contact’s first name.
​
last
string
The contact’s last name.
​
display_name
string
The full display name shown in the inbox.
​
email
string
The contact’s email address.
​
custom
object
Custom field values keyed by numeric field ID string. For example, {"123": "Premium"}. Use POST /v1/contact-fields to retrieve the available field IDs for your team.
​
avatar
string
URL of an image to use as the contact’s avatar.
​
assignee_id
integer
ID of the user to assign this contact to. Pass -1 to unassign.
​
tags
array
List of tag objects, each with a tag_id integer. Maximum of 5 tags.
​
is_opted_out
boolean
Set to true to mark the contact as opted out.

​
Response

​
id
integer
Integer ID of the updated contact.
​
rev
integer
New revision number after the update.
​
uuid
string
UUID of the contact.

​
Examples

Basic update — name and email:
curl -X PUT https://api.heymarket.com/v1/contact/98765 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "15105553344",
    "first": "Updated",
    "last": "Name",
    "email": "updated@example.com"
  }'
Update with custom fields (merge):
curl -X PUT https://api.heymarket.com/v1/contact/98765 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "15105553344",
    "custom": {
      "123": "Premium",
      "456": "Enterprise"
    }
  }'
Overwrite all custom fields:
curl -X PUT "https://api.heymarket.com/v1/contact/98765?overwrite=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "15105553344",
    "custom": {
      "123": "Starter"
    }
  }'

​
How to update custom fields

1

Retrieve available field IDs

Call POST /v1/contact-fields to get the list of custom fields defined for your team. Each field has a numeric id.
curl -X POST https://api.heymarket.com/v1/contact-fields \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
2

Identify the field you want to update

Find the field by its name in the response and note its numeric id.
3

Build the custom object

Use the numeric ID as a string key in the custom object. For example, if the field ID is 123, use "123" as the key.
{
  "custom": {
    "123": "Premium"
  }
}
4

Send the update request

Call PUT /v1/contact/{id} or PUT /v2/contact/{contactID} with your custom object in the request body.