---
name: companies
description: >
  Instructs AI agents how to create, read, update, and delete company entities
  in Kyriba. Companies are the core organizational unit - all bank accounts,
  cash flows, and transactions belong to a company.
version: 1.0.0
scopes:
  - company-scope
authors:
  - kyriba
tags:
  - kyriba
  - platform
  - companies
  - 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: Companies

---

## Required Kyriba Permission

```
company-scope
```

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

---

## Base Path

```
/v1/companies
```

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/companies` | List companies (all or filtered) |
| `POST` | `/v1/companies` | Create a new company |
| `POST` | `/v1/companies/details` | Get full details for multiple companies by refs |
| `GET` | `/v1/companies/{ref}` | Get a specific company by uuid or code |
| `PUT` | `/v1/companies/{ref}` | Update a specific company |
| `DELETE` | `/v1/companies/{ref}` | Delete a specific company |

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

---

## Filterable & Sortable Fields

```
code, uuid, description1, description2, shortCode,
interfaceCode, defaultGroup.uuid, defaultGroup.code,
businessIdentifiers.otherIdentifierType,
businessIdentifiers.otherIdentifierValue,
businessIdentifiers.txp,
address.country.code, address.country.uuid
```

---

## Example Requests

**List all companies:**
```
GET /v1/companies?page.limit=100&page.offset=0
```

**GET list response:**
```json
{
  "metadata": {
    "pageLimit": 100,
    "pageOffset": 0,
    "pageResults": 2,
    "numberOfTotalResults": 2
  },
  "results": [ ... ]
}
```
> Response key is always `results`. Stop paginating when `len(results) < pageLimit`.

**Filter by country:**
```
GET /v1/companies?filter=address.country.code==FR
```

**Filter by code pattern:**
```
GET /v1/companies?filter=code==COMP*&sort=code
```

**Get multiple companies by refs (bulk):**
```http
POST /v1/companies/details
Content-Type: application/json

{
  "refs": ["MY_COMPANY", "b2e8a5fa-413b-b53a-85729d16317b"]
}
```

**Create a new company:**
```http
POST /v1/companies
Content-Type: application/json

{
  "code": "MY_COMPANY",
  "description1": "My Company Name",
  "shortCode": "MCO",
  "interfaceCode": "MCO_ERP",
  "address": {
    "country": { "code": "FR" },
    "city": "Paris",
    "street1": "1 Rue de la Paix",
    "zipCode": "75001"
  }
}
```

**Create response:**
```json
{ "uuid": "b2e8a5fa-413b-b53a-85729d16317b" }
```

---

## Key Fields

| Field | Description |
|---|---|
| `code` | Unique company code (primary identifier) |
| `uuid` | System-generated unique identifier |
| `description1` | Company name |
| `description2` | Secondary description |
| `shortCode` | Short company code (must be unique) |
| `interfaceCode` | ERP/external system identifier (must be unique) |
| `defaultGroup` | Default company group (`{ "code": "..." }`) |
| `address` | Company address including country (required) |
| `businessIdentifiers` | External identifiers (LEI, tax ID, etc.) |

---

## Critical Rules

1. `uuid` is auto-generated - do not pass it in `POST` body
2. Uniqueness is enforced on `code`, `shortCode`, and `interfaceCode`
3. `address.country` is required on create
4. Use `POST /v1/companies/details` for bulk retrieval
5. A `409 Conflict` on delete means the company has linked data (accounts, cash flows, etc.)

---

## Error Reference

| Status | Meaning |
|---|---|
| `201` | Company created - returns `{ "uuid": "..." }` |
| `400` | Bad request - invalid fields or missing required data |
| `401` | Authentication required or token expired |
| `403` | Required Kyriba permission not configured on your API client |
| `404` | Company not found for given `{ref}` |
| `409` | Conflict - code/shortCode/interfaceCode already exists, or company in use |
| `415` | Wrong Content-Type (must be `application/json`) |

---

## OpenAPI Spec & Postman Collection

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