---
title: "Upsert a company group"
method: POST
path: "/public/v1/company-groups"
tags: ["CompanyGroup"]
---

# Upsert a company group

`POST /public/v1/company-groups`

Creates or renames a single company group in one endpoint. Pass `id` to rename the matching
existing group; omit `id` to create a new one. A create responds 201, an update responds 200.
Company groups are the labels you use to organize your business relationships (customers and
vendors); price tiers can target or exclude companies by group.

`name` is required and must be unique within your company — reusing a name already taken by
another of your groups is rejected with a 400. On update, `name` fully replaces the stored name;
there are no other editable fields, so this endpoint only ever sets the group's name.

Renaming a group does not change its ID, so any price tier that already targets or excludes this
group keeps doing so under the new name. Creating a group does not attach it to any company
relationship — membership is managed separately.

Required permission: `settings_permissions_company_relationship_groups`.

## Request body

- object
  - `id` string — ID of the group to update. Present → the matching group owned by your company is renamed (404 if no such group exists for you). Absent → a new group is created.
  - `name` string, required — Display name of the company group. Required on both create and update. Leading/trailing whitespace is trimmed, and the result must be non-empty, at most 255 characters, and unique among your company's groups (a duplicate returns 400). Allowed characters are letters, digits, spaces, underscores, and `~#-$/|%&'().`; it may not contain two colons in sequence (`::`). Any other character is rejected with a 400. On update this replaces the existing name.

## Response `200`

The updated company group

## Other responses

- `201` — The created company group
- `400` — Invalid parameters
- `401` — Missing or invalid API token
- `403` — The API token lacks the required permission
- `404` — Not Found

---

[API](https://skmtc.dev/distru/apis/distru-api.md) · [All operations](https://skmtc.dev/distru/apis/distru-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/distru/distru-api/revisions/f8930b2c2924/schema)