Update Company
curl --request PUT \
--url https://app.cometly.com/public-api/v1/companies/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"domain": {},
"external_id": {},
"name": "<string>"
}
'import requests
url = "https://app.cometly.com/public-api/v1/companies/{id}"
payload = {
"domain": {},
"external_id": {},
"name": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({domain: {}, external_id: {}, name: '<string>'})
};
fetch('https://app.cometly.com/public-api/v1/companies/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.cometly.com/public-api/v1/companies/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'domain' => [
],
'external_id' => [
],
'name' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.cometly.com/public-api/v1/companies/{id}"
payload := strings.NewReader("{\n \"domain\": {},\n \"external_id\": {},\n \"name\": \"<string>\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://app.cometly.com/public-api/v1/companies/{id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"domain\": {},\n \"external_id\": {},\n \"name\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.cometly.com/public-api/v1/companies/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"domain\": {},\n \"external_id\": {},\n \"name\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": 123,
"domain": {},
"external_id": {},
"name": "<string>",
"message": "<string>",
"field": "<string>",
"conflicting_company_id": 123
}Companies
Update Company
Update an existing company’s domain, external ID, or name
PUT
/
public-api
/
v1
/
companies
/
{id}
Update Company
curl --request PUT \
--url https://app.cometly.com/public-api/v1/companies/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"domain": {},
"external_id": {},
"name": "<string>"
}
'import requests
url = "https://app.cometly.com/public-api/v1/companies/{id}"
payload = {
"domain": {},
"external_id": {},
"name": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({domain: {}, external_id: {}, name: '<string>'})
};
fetch('https://app.cometly.com/public-api/v1/companies/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.cometly.com/public-api/v1/companies/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'domain' => [
],
'external_id' => [
],
'name' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.cometly.com/public-api/v1/companies/{id}"
payload := strings.NewReader("{\n \"domain\": {},\n \"external_id\": {},\n \"name\": \"<string>\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://app.cometly.com/public-api/v1/companies/{id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"domain\": {},\n \"external_id\": {},\n \"name\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.cometly.com/public-api/v1/companies/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"domain\": {},\n \"external_id\": {},\n \"name\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": 123,
"domain": {},
"external_id": {},
"name": "<string>",
"message": "<string>",
"field": "<string>",
"conflicting_company_id": 123
}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
integer
required
The unique identifier of the company to update.
Request Body
At least one ofdomain, external_id, or name must be provided.
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 below. Maximum 255 characters.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 below. Floats, arrays, and booleans are rejected with a 422.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.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.integer
The unique identifier of the company.
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.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.string
The name currently associated with this company.
Error Response
string
Error description explaining what went wrong.
409 conflict, the response also includes:
string
The identifier field that caused the conflict:
domain or external_id.integer
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
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"
}'
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
$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);
?>
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 |
Notes
- Rate Limit: This endpoint has a limit of 60 requests per minute per Space. See Rate Limiting 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, ornameis rejected with a 422 error. domainandexternal_idare identifiers, not just labels:domaindetermines which company future events from that email domain are matched to;external_iddetermines which company future events carrying thatcompany_external_idare 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:
domainvalues are trimmed and lowercased before storing, to match how the tracker resolves domains during ingestion.external_idvalues are trimmed but case is preserved —ACCT_1andacct_1are different ids — 1 to 190 characters after trimming; integers are accepted and stored as their decimal string. A blank string is treated asnullfor either field. domain: nullorexternal_id: nullreleases the claim: the company keeps itsid, history, and contacts, but future events matching that identifier will create or match a different company. Re-sending the current value is a no-op200.- Identifier conflicts are rejected, not merged: if the new
domainorexternal_idalready belongs to another company in the Space, the request fails with409andconflicting_company_idnaming the owner, withfieldnaming which identifier conflicted. Nothing is written. Re-point contacts to the existing company, or update it directly, instead of retrying. external_idonly affects ingestion in External ID mode: event ingestion only groups bycompany_external_idwhen 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.namecannot be cleared: unlikedomainandexternal_id,nameis a required column in the tracker. Sendingname: nullreturns a422— omit the key instead if you don’t want to change it.