Skip to main content
PUT
/
public-api
/
v1
/
contacts
/
{id}
Update Contact
curl --request PUT \
  --url https://app.cometly.com/public-api/v1/contacts/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "emails": [
    "<string>"
  ],
  "phones": [
    "<string>"
  ],
  "names": [
    "<string>"
  ],
  "locations": [
    "<string>"
  ],
  "custom_fields": {}
}
'
{
  "id": 123,
  "emails": [
    {}
  ],
  "phones": [
    {}
  ],
  "names": [
    {}
  ],
  "locations": [
    {}
  ],
  "custom_fields": {},
  "message": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.cometly.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

This endpoint updates an existing contact using sparse PUT semantics. Any field you include in the request body is treated as the full, authoritative list for that collection — existing values are deleted and replaced with the values you provide. Any field you omit is left untouched. This design lets you change one aspect of a contact (e.g. add a phone number) without having to send the contact’s entire state. However, you must include the complete list for any field you choose to update — sending emails: ["a@x.com"] will remove every other email already on the contact.

​
Path Parameters

​
id
integer
required
The unique identifier of the contact to update. Merged profile aliases are automatically resolved to the current canonical profile.

​
Request Body

At least one of emails, phones, names, locations, or custom_fields must be provided.
​
emails
string[]
Full replacement list of email addresses. Provide the complete authoritative array — anything not included is removed. Provide [] to wipe all emails. The first item becomes the primary email on the contact’s profile.
​
phones
string[]
Full replacement list of phone numbers. Provide [] to wipe all phones. The first item becomes the primary phone.
​
names
string[]
Full replacement list of names. Provide [] to wipe all names. The first item becomes the primary name.
​
locations
string[]
Full replacement list of locations. Provide [] to wipe all locations. The first item becomes the primary location.
​
custom_fields
object
Full replacement object of custom profile fields keyed by field slug (profile_field_1 through profile_field_30). When provided, every key NOT included is set to null. Provide {} to wipe all 30 custom fields. Fields 1-15 accept text (max 10,240 chars), 16-25 accept numbers, 26-30 accept dates.

​
Response

​
Success Response

Returns the updated contact with only the fields that were modified. Omitted request fields are not echoed back.
​
id
integer
The unique identifier of the contact (after resolving merged-profile aliases).
​
emails
array
The new list of emails, if emails was provided in the request.
​
phones
array
The new list of phone numbers, if phones was provided in the request.
​
names
array
The new list of names, if names was provided in the request.
​
locations
array
The new list of locations, if locations was provided in the request.
​
custom_fields
object
The new custom fields object, if custom_fields was provided in the request.

​
Error Response

​
message
string
Error description explaining what went wrong.

​
Example Requests

curl -X PUT "https://app.cometly.com/public-api/v1/contacts/12345" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["john@example.com", "john.doe@example.com"],
    "phones": ["+1234567890"],
    "custom_fields": {
      "profile_field_1": "Enterprise",
      "profile_field_16": "500"
    }
  }'

​
Status Codes

Status CodeDescription
200Contact successfully updated
401Missing or invalid API key
403API key doesn’t have permission or subscription is inactive
404Contact not found
422Invalid parameters provided (check error message for details)
429Too many requests - rate limit exceeded. See Rate Limiting

​
Notes

  • Rate Limit: This endpoint has a limit of 60 requests per minute per Space. See Rate Limiting for details.
  • Sparse PUT semantics: Omitted fields are NOT modified. Provided fields are treated as the complete authoritative state for that collection.
  • To add a value without losing existing data, first call Get Contact to retrieve the current array, then PUT the merged list.
  • Custom fields are all-or-nothing: providing a custom_fields object sets ALL 30 columns — keys not in the object are cleared to null. To preserve unchanged fields, include them in the object.
  • Empty arrays wipe a collection: phones: [] removes every phone row for the contact and sets the primary phone to null.
  • Merged profiles: If you pass an ID that was merged into another profile, the update is applied to the canonical (current) profile.
  • Transaction Safety: Updates are wrapped in a database transaction to ensure data consistency.