Skip to main content
PUT
Update Company

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 of domain, 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 preservedACCT_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.
On a 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

Status Codes

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, 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 preservedACCT_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.