POST
Add a role to a company
Organization space User accounts only For: Administrator · Permission: companies.update Conditions
  • roles must be present (it may be an empty list) and contain distinct 27-character identifiers.
  • Every identifier must designate a capability group for which the company holds a built-in role whose name starts with manage; groups whose roles contain permissions excluded from built-in roles by configuration, or unknown groups, are refused with a validation error on roles.
What else happens
  • Attaches the matching built-in capability roles to the company, which changes what the company’s members and agent accounts can do in features that check both the company’s roles and the person’s permission (the catalogue, for example).
  • Answers the company with its settings.
Part of Run the organization and its companies.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

company
string
required

Identifier of the company (27-character KSUID string). It must belong to the organization.

Body

application/json
roles
string[]
required

Identifiers of capability groups (27-character KSUID strings, distinct) to attach to or detach from the company. Required; an empty list is accepted and changes nothing. Each must match a built-in manage role the company holds, otherwise a validation error is returned.

Required string length: 27

Response

legacy payload: the company renders its settings, loaded here because a Resource never lazy-loads

CompanyResource

id

Identifier of the company (27-character KSUID string).

name

Name of the company, stored in lowercase.

city

City of the company; null when not set.

tax_registration_number

Tax registration number of the company; null when not set.

business_registration_number

Business registration number of the company; null when not set.

address

Street address of the company; null when not set.

working_hours
object | null

Opening hours of the company, as an object keyed by weekday (monday to sunday) holding lists of HH:MM-HH:MM ranges, plus an optional exceptions object keyed by date (YYYY-MM-DD or MM-DD). When set, the company can only be used within these hours, in the company's time zone. Null when not set.

country

Country of the company as free text; null when not set. The coded country used for taxes is a separate field set on update.

is_active
boolean

Whether the company is active. An organization turns it on or off with the activate and deactivate actions.

logo_url

Public URL of the stored logo image, or null when no logo is set.

subscription_activated_at

Date and time the company's subscription was activated (ISO 8601); null when never activated. Not set by this API.

trial_ended_at

Date and time the company's trial ended or ends (ISO 8601); null when not set. Not set by this API.

next_billing_at

Date and time of the next billing (ISO 8601); null when not set. Not set by this API.

activated_at

Date and time the company was activated (ISO 8601). Set to the creation time when an organization creates the company.

owner_id

Identifier of the member who owns the company (27-character KSUID string); the creator when an organization creates the company.

cash_account_id

Identifier of the accounting cash account of the company (27-character KSUID string), created when its books are opened; null if not yet created. It is an account of the company's books, not a cash register's ledger account.

created_at

Date and time the record was created (ISO 8601, UTC).

updated_at

Date and time the record was last changed (ISO 8601, UTC).

parent
string | null
settings
object

Settings of the company (time zone, currency, rounding, default tax and discount rules). Rendered only when the include is selected, or in the role assignment answers.