> ## 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.

# Update Contact

> Update an existing contact's emails, phones, names, locations, or custom fields

## 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** `string`

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

```bash cURL theme={null}
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"
    }
  }'
```

```javascript JavaScript theme={null}
const contactId = 12345;
const response = await fetch(`https://app.cometly.com/public-api/v1/contacts/${contactId}`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    emails: ['john@example.com', 'john.doe@example.com'],
    phones: ['+1234567890'],
    custom_fields: {
      profile_field_1: 'Enterprise',
      profile_field_16: '500'
    }
  })
});

const data = await response.json();
console.log('Updated contact:', data);
```

```php PHP theme={null}
<?php
$contactId = 12345;
$url = 'https://app.cometly.com/public-api/v1/contacts/' . $contactId;
$headers = [
    'Authorization: Bearer YOUR_API_KEY',
    'Accept: application/json',
    'Content-Type: application/json'
];

$data = [
    'emails' => ['john@example.com', 'john.doe@example.com'],
    'phones' => ['+1234567890'],
    'custom_fields' => [
        'profile_field_1' => 'Enterprise',
        'profile_field_16' => '500',
    ],
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$result = json_decode($response, true);
curl_close($ch);
?>
```

```python Python theme={null}
import requests

contact_id = 12345
url = f'https://app.cometly.com/public-api/v1/contacts/{contact_id}'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
}

data = {
    'emails': ['john@example.com', 'john.doe@example.com'],
    'phones': ['+1234567890'],
    'custom_fields': {
        'profile_field_1': 'Enterprise',
        'profile_field_16': '500',
    },
}

response = requests.put(url, headers=headers, json=data)
result = response.json()
```

## Status Codes

| Status Code | Description |
| - | - |
| 200 | Contact successfully updated |
| 401 | Missing or invalid API key |
| 403 | API key doesn't have permission or subscription is inactive |
| 404 | Contact not found |
| 422 | Invalid parameters provided (check error message for details) |
| 429 | Too many requests - rate limit exceeded. See [Rate Limiting](https://docs.cometly.com/introduction/rate-limiting.md) |

## Notes

* **Rate Limit**: This endpoint has a limit of **60 requests per minute** per Space. See [Rate Limiting](https://docs.cometly.com/introduction/rate-limiting.md) 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](https://docs.cometly.com/api-reference/endpoint/get-contact.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.