---
name: company-groups
description: >
  Instructs AI agents how to create, read, update, and delete company groups
  in Kyriba. Company groups organize multiple companies for reporting, filtering,
  and process access control.
version: 1.0.0
scopes:
  - company-group-scope
authors:
  - kyriba
tags:
  - kyriba
  - platform
  - company-groups
  - api
---

> **Auth** — POST {AUTH_BASE_URL}/oauth/token · Basic base64(CLIENT_ID:CLIENT_SECRET) · no scope.
> Use token_type verbatim — do not hardcode `Bearer`. On 401: retry once with the other scheme (`token` vs `Bearer`). On 429: wait Kyriba-Customer-Rate-Limit-Reset.

# Kyriba API Skill: Company Groups

---

## Required Kyriba Permission

```
company-group-scope
```

>  Note: scope is `company-group-scope` (singular), not `company-groups-scope`.

This is a Kyriba access permission — not an OAuth scope parameter. Do NOT add `scope=` to the token request.

---

## What are Company Groups?

A Company Group is a named collection of companies used to filter and group companies in processes and reporting. A company can belong to multiple groups. Each group has an optional leader company.

---

## Base Path

```
/v1/company-groups
```

---

## Endpoints

`{ref}` accepts either `uuid` or `code`.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/company-groups` | List company groups |
| `POST` | `/v1/company-groups` | Create a new company group |
| `GET` | `/v1/company-groups/{ref}` | Get a specific company group |
| `PUT` | `/v1/company-groups/{ref}` | Update a specific company group |
| `DELETE` | `/v1/company-groups/{ref}` | Delete a specific company group |

---

## Filterable & Sortable Fields

```
code, uuid, description, leader.uuid, leader.code,
intermediary, counterparty, company.uuid, company.code
```

---

## Example Requests

**List all company groups:**
```
GET /v1/company-groups?page.limit=100&page.offset=0&sort=code
```

**Find groups containing a specific company:**
```
GET /v1/company-groups?filter=company.code==COMP_FR
```

**Find intermediary groups:**
```
GET /v1/company-groups?filter=intermediary==true
```

**Create a company group:**
```http
POST /v1/company-groups
Content-Type: application/json

{
  "code": "GRP_EUROPE",
  "description": "European entities",
  "leader": { "code": "COMP_FR" },
  "companies": [
    { "code": "COMP_FR" },
    { "code": "COMP_DE" },
    { "code": "COMP_ES" }
  ]
}
```

**Create response:** `{ "uuid": "..." }`

**List response:**
```json
{
  "metadata": { "total": 5, "count": 5, "limit": 100, "offset": 0 },
  "results": [
    {
      "code": "GRP_EUROPE",
      "uuid": "...",
      "description": "European entities",
      "leader": { "code": "COMP_FR", "uuid": "..." },
      "intermediary": false,
      "counterparty": false
    }
  ]
}
```

>  The list endpoint does **NOT** return the `companies` array. To retrieve member companies, call `GET /v1/company-groups/{ref}` for each group individually. For N groups this costs N+1 API calls.

---

## Key Fields

| Field | Description |
|---|---|
| `code` | Unique group code |
| `uuid` | System-generated identifier |
| `description` | Human-readable label. **Can be `null`**. |
| `leader` | Leader company `{ "code": "...", "uuid": "..." }`. **Can be `null`**. |
| `companies` | Array of member companies `[{ "code": "...", "uuid": "..." }]` |
| `intermediary` | `true` if group is used as an intermediary entity |
| `counterparty` | `true` if group is used as a counterparty |

---

## Critical Rules

1. `uuid` is auto-generated - do not include in POST body
2. **No PATCH endpoint** - adding one company requires: `GET` (full object) -> append to `companies` array -> `PUT` full object back (minus `uuid`)
3. `PUT` returns `204 No Content` on success
4. On `PUT`, send the complete object from `GET` with only `companies` modified - omitting `leader`, `intermediary`, or `counterparty` may reset them
5. A company group cannot be deleted if it is referenced by processes or reports (`409`)
6. Uniqueness enforced on `code`

---

## Error Reference

| Status | Meaning |
|---|---|
| `201` | Created - returns `{ "uuid": "..." }` |
| `400` | Missing required fields |
| `403` | Required Kyriba permission not configured on your API client |
| `404` | Group not found |
| `409` | Code already exists or group in use |

---

## OpenAPI Spec & Postman Collection

- OpenAPI: `https://developer.kyriba.com/static/apis/company-groups/company-groups.yaml`
- Postman: `https://developer.kyriba.com/static/apis/company-groups/company-groups-postman-collection.json`