Update company attributes

put/v1/companies/{id}
Requires any one of these rolesAbout roles
org.permission.company.update
Legacyorg.user.company.write

The API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.

Updates the attributes of a company based on the company ID.

Note

This endpoint is subject to Object Rate Limiting, which limits how many updates a single user can make to a single company attribute. To learn more, see Rate limiting.

Setting deleted: true on a company that still has one or more children in a hierarchy tree (see Companies (Hierarchy)) returns a 409 conflict naming the first blocking child and the tree it appears in, and does not delete the company. The check spans every hierarchy tree the company participates in — not just company_hierarchy. Unlink or delete that child first — for example with DELETE /kedge/{childId}/parent?name=<tree>, using the tree name from the error message. If the company has blocking children in more than one tree, repeat until all are cleared.

Custom Attributes

Custom attributes are optional and allow you to specify custom key-value pairs.

Kustomer uses a naming convention for custom attributes to specify the field data type with a name suffix:

Naming Suffix

  • Num number or null
  • At date-time or null
  • Str string or null, length: [ 0 .. 1024 ] characters
  • Txt string or null, length: [ 0 .. 1024 ] characters
  • Bool boolean or null
  • Url string or null, format: uri
About this resource

Companies

A company is an organization that your customers belong to, such as a business account. It holds the organization's contact details, tags and custom attributes, can own custom objects, and can sit in a parent-child hierarchy with other companies.

Companies group customers who belong to the same organization, which matters most for B2B support: agents can see which account a person works for, and searches, workflows and reports can filter on company data. A customer links to one company through its company attribute, which holds the company ID. Companies are usually created by a CRM sync or an import, then kept up to date as the source system changes. There is no DELETE endpoint: you delete a company by updating it with deleted: true.

Key fields

name is the only required field. Set externalId to the account's ID in your own system so you can find it again: GET /v1/companies accepts externalId, or filter for a name match, but if you send both, both are ignored. The contact lists emails, phones, whatsapps, socials, urls, domains and locations each hold up to 10 entries, and tags holds up to 20. Your own fields go in custom, named with a type suffix such as tierStr or seatsNum; see custom attributes.

Updates merge into the existing company by default. Add replace=true to replace the whole resource. Updates are subject to object rate limiting, which caps how often one user can change the same company; see rate limits.

Hierarchies

The hierarchy endpoints link existing companies into trees, such as a parent company and its subsidiaries. Each link is an edge of type kedge with its own ID: sourceId is the parent and targetId is the child. Edges belong to a named tree (name, default company_hierarchy), and a company has at most one parent per tree, so setting a new parent replaces the old edge. A tree can be at most 20 levels deep and hold at most 2,000 companies. Cycles and self-parenting fail with 400.

Most hierarchy endpoints take a company ID. The exception is DELETE /v1/kedge/{id}, which takes an edge ID. Reading a company returns a kedge-node with its parent edge, one page of direct children, and breadcrumbs from the root down to the company itself.

Which endpoint to use

To Call
List companies, or find one by externalId or name GET /v1/companies
Create, read or update a company (including deleting it with deleted: true) POST /v1/companies, GET or PUT /v1/companies/{id}
List a company's custom objects of one Klass GET /v1/companies/{id}/klasses/{name}
Create or update up to 100 companies at once POST or PUT /v1/companies/bulk
Link a child to a parent POST /v1/kedge or POST /v1/kedge/{id}/parent
Read a company's place in the tree GET /v1/kedge/{id}, or GET /v1/kedge/{id}/parent for just the parent edge (404 for a root)
Make a company a root, keeping its children DELETE /v1/kedge/{id}/parent
Delete one edge by its edge ID DELETE /v1/kedge/{id}

Bulk requests run asynchronously and return a bulk operation; poll it with the bulk operations endpoints. Add _clientRef to every item to match per-item results back to your rows. Deleting a company that still has children in any tree fails with 409 Conflict, naming the first blocking child and its tree; unlink or delete that child first. A 409 on an edge write means another write to the same tree was in progress, so retry it.

RelatedCustomersModel company hierarchiesBulk operationsKObjects (custom objects)

Path parameters

idstringrequired

Company ID.

Example "6195640664b2fbb9eddc1e9b"

Query parameters

replaceboolean

Set to true to replace the full resource instead of applying patch semantics.

Example true

Request body

application/jsonrequired
namestring
min length 3 · max length 256
externalIdstringnullable
max length 256
avatarUrlstring<uri>nullable
array<email>
max items 10 · unique items
array<phone>
max items 10 · unique items
array<whatsapp>
max items 10 · unique items
array<social>
max items 10 · unique items
array<url>
max items 10 · unique items
array<domain>
max items 10 · unique items
array<location>
max items 10 · unique items
employeeCountnumber
tagsarray<tag_name>
max items 20 · unique items
customobjectcustom_attrs
defaultLangstringlangnullable
max length 100
revnumber
deletedbooleannullable

Responses

OK

objectrequired