Bulk create companies

post/v1/companies/bulk
Requires any one of these rolesAbout roles
org.permission.company.create
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.

Creates companies in bulk.

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

_clientRef support: You can include an optional _clientRef string on each item for per-item result correlation. See Bulk create customers for full documentation of rules, the async poll flow, and the results[] response shape.

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)

Request body

application/jsonrequired

array<object>

namestringrequired
min length 3 · max length 256
externalIdstring
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
createdAtstring<date-time>
importedAtstring<date-time>
revnumber
customobjectcustom_attrs
defaultLangstringlangnullable
max length 100
_clientRefstringclient_ref

Optional client-supplied correlation token. Omit the field to rely on the existing objectIds and errors fields. When included, it must be present on every item in the request (all-or-nothing), and must be unique within the request array. See Bulk create customers for full documentation of rules, the async poll flow, and the results[] response shape.

min length 1 · max length 255

Responses

Created

objectrequired