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

> Update an existing company's domain, external ID, or name

## Overview

This endpoint updates an existing company using **sparse PUT** semantics. Any field you include is replaced with the value you provide; any field you omit is left untouched.

## Path Parameters

**id** `integer` *required*

The unique identifier of the company to update.

## Request Body

At least one of `domain`, `external_id`, or `name` must be provided.

**domain** `string | null`

New domain for the company. **This is an identifier, not just a label**: it decides which company future events from that email domain are matched to. The value is trimmed and lowercased before storing, matching ingestion — a blank string is treated as `null`. Omit the key to leave the existing domain untouched.

Sending `null` (or blank) releases the company's domain claim: the company keeps its `id`, history, and contacts, but future events from that domain will create or match a different company instead. Re-sending the current domain is a no-op `200`.

If the new domain already belongs to another company in the Space, the request is rejected with `409` and nothing is changed — see [Error Response](#error-response) below. Maximum 255 characters.

**external\_id** `string | integer | null`

New external ID for the company — your own account/company identifier, the same value you send as `company_external_id` on events. **This is an identifier, not just a label**: it decides which company future events carrying that `company_external_id` are matched to. Unlike `domain`, it is stored byte-exact: trimmed, but case is **preserved** — `ACCT_1` and `acct_1` are two different ids. 1 to 190 characters after trimming; a blank string is treated as `null`. Integers are accepted and stored as their decimal string (e.g. `1234567`). Omit the key to leave the existing external ID untouched.

Sending `null` (or blank) releases the company's claim on the external ID: the company keeps its `id`, history, and contacts, but future events carrying that `company_external_id` will create or match a different company instead. Re-sending the current external ID is a no-op `200`.

If the new external ID already belongs to another company in the Space, the request is rejected with `409` and nothing is changed — see [Error Response](#error-response) below. Floats, arrays, and booleans are rejected with a `422`.

> [!NOTE]
>
> Ingestion only groups by `company_external_id` when the Space's company identity mode (Space Settings → Additional Setup → Company Tracking) is set to **External ID**. In the default **Auto** mode, the value you set here is stored and returned by this API, but event ingestion groups companies by email domain and ignores `company_external_id`.

**name** `string`

New name for the company. Omit to leave the existing name untouched. Maximum 255 characters. Cannot be `null` — the stored value is a required column, so sending `name: null` returns a `422`.

## Response

### Success Response

Returns the full company object after the update.

**id** `string`

The unique identifier of the company.

**domain** `string | null`

The domain currently associated with this company. `null` if the company has no domain claim — either it was created from a customer-supplied external ID alone, or its domain was released via this endpoint.

**external\_id** `string | null`

The external ID currently associated with this company. `null` if the company has no external ID claim — either it was created from an email domain alone, or its external ID was released via this endpoint.

**name** `string`

The name currently associated with this company.

### Error Response

**message** `string`

Error description explaining what went wrong.

On a `409` conflict, the response also includes:

**field** `string`

The identifier field that caused the conflict: `domain` or `external_id`.

**conflicting\_company\_id** `string`

The ID of the company in this Space that already owns the given `domain` or `external_id` (see `field`). Re-point contacts to that company, or update it directly, instead of retrying this request.

## Example Requests

```bash cURL theme={null}
curl -X PUT "https://app.cometly.com/public-api/v1/companies/12345" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "acme.io",
    "external_id": "acct_8f3k2",
    "name": "Acme Inc"
  }'
```

```javascript JavaScript theme={null}
const companyId = 12345;
const response = await fetch(`https://app.cometly.com/public-api/v1/companies/${companyId}`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    domain: 'acme.io',
    external_id: 'acct_8f3k2',
    name: 'Acme Inc'
  })
});

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

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

$data = [
    'domain' => 'acme.io',
    'external_id' => 'acct_8f3k2',
    'name' => 'Acme Inc',
];

$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

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

data = {
    'domain': 'acme.io',
    'external_id': 'acct_8f3k2',
    'name': 'Acme Inc',
}

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

## Status Codes

| Status Code | Description |
| - | - |
| 200 | Company successfully updated |
| 401 | Missing or invalid API key |
| 403 | API key doesn't have permission or subscription is inactive |
| 404 | Company not found |
| 409 | The given `domain` or `external_id` already belongs to another company in this Space. Nothing is changed. |
| 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**: Only the fields you include in the request body are modified. Other columns are left untouched.
* **At least one field is required**: A request with none of `domain`, `external_id`, or `name` is rejected with a 422 error.
* **`domain` and `external_id` are identifiers, not just labels**: `domain` determines which company future events from that email domain are matched to; `external_id` determines which company future events carrying that `company_external_id` are matched to. Changing either moves the company's claim on that identifier away from wherever it lived before.
* **Domains are normalized, external IDs are byte-exact**: `domain` values are trimmed and lowercased before storing, to match how the tracker resolves domains during ingestion. `external_id` values are trimmed but case is **preserved** — `ACCT_1` and `acct_1` are different ids — 1 to 190 characters after trimming; integers are accepted and stored as their decimal string. A blank string is treated as `null` for either field.
* **`domain: null` or `external_id: null` releases the claim**: the company keeps its `id`, history, and contacts, but future events matching that identifier will create or match a different company. Re-sending the current value is a no-op `200`.
* **Identifier conflicts are rejected, not merged**: if the new `domain` or `external_id` already belongs to another company in the Space, the request fails with `409` and `conflicting_company_id` naming the owner, with `field` naming which identifier conflicted. Nothing is written. Re-point contacts to the existing company, or update it directly, instead of retrying.
* **`external_id` only affects ingestion in External ID mode**: event ingestion only groups by `company_external_id` when the Space's company identity mode (Space Settings → Additional Setup → Company Tracking) is set to **External ID**. In the default **Auto** mode, the value set here is stored and returned by this API but ignored for grouping.
* **`name` cannot be cleared**: unlike `domain` and `external_id`, `name` is a required column in the tracker. Sending `name: null` returns a `422` — omit the key instead if you don't want to change it.


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