---
name: bank-account-groups
description: >
  Instructs AI agents how to create, read, update, and delete bank account
  groups in Kyriba, and how to add or remove member accounts. Account groups
  are used for cash pooling and batch operations.
version: 1.0.0
scopes:
  - account-group-scope
authors:
  - kyriba
tags:
  - kyriba
  - platform
  - bank-accounts
  - 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: Bank Account Groups

---

## Required Kyriba Permission

```
account-group-scope
```

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

---

## What are Bank Account Groups?

Group bank accounts together for cash pooling, batch reporting, and access control. Each group may designate a pooling account and contains a list of member bank accounts.

---

##  Base URL - Two things to note

```
https://api.demo.kyriba.com/api/v1/account-groups
```

1. The path is `/api/v1/account-groups` - **not** `/api/v1/bank-account-groups`
2. Requires the `/api` prefix - `https://api.demo.kyriba.com/v1/account-groups` returns 404

---

## Endpoints

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

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/account-groups` | List account groups |
| `POST` | `/api/v1/account-groups` | Create an account group |
| `GET` | `/api/v1/account-groups/{ref}` | Get a specific group (includes `accounts[]` and `poolingAccount`) |
| `PUT` | `/api/v1/account-groups/{ref}` | Update a group |
| `DELETE` | `/api/v1/account-groups/{ref}` | Delete a group |
| `POST` | `/api/v1/account-groups/{ref}/accounts` | Add account(s) to a group |
| `DELETE` | `/api/v1/account-groups/{ref}/accounts` | Remove account(s) from a group |

---

## Pagination

Uses standard `page.limit` / `page.offset`.

---

## Filterable Fields

```
code, description, hasAttachments, poolingAccount.code, poolingAccount.uuid
```

---

## Key Fields

| Field | Description |
|---|---|
| `uuid` | System-generated identifier |
| `code` | Unique group code |
| `description` | Group description. **Can be `null`**. |
| `poolingAccount` | Designated pooling account `{ "code": "...", "uuid": "..." }`. **Can be `null`**. |
| `accounts[]` | Member bank accounts - **only present in `GET /{ref}`**, not in list response |
| `hasAttachments` | `true` if group has file attachments |

---

## Example Requests

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

**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`.

**Get a group with its member accounts:**
```
GET /api/v1/account-groups/GRP_EUR_POOL
```

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

{
  "code": "GRP_EUR_POOL",
  "description": "EUR Cash Pool",
  "poolingAccount": { "code": "POOL_EUR_001" }
}
```

**Add accounts to a group:**
```http
POST /api/v1/account-groups/GRP_EUR_POOL/accounts
Content-Type: application/json

[
  { "code": "ACC_FR_001" },
  { "code": "ACC_DE_002" }
]
```

**Remove accounts from a group:**
```http
DELETE /api/v1/account-groups/GRP_EUR_POOL/accounts
Content-Type: application/json

[
  { "code": "ACC_DE_002" }
]
```

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

---

## Critical Rules

1. `uuid` is auto-generated - do not include in POST body
2. `accounts[]` and `poolingAccount` are **only in `GET /{ref}`** - the list endpoint omits them
3. `description` can be `null` - always use `.get('description') or ''` when formatting
4. Path is `/api/v1/account-groups` - **not** `/api/v1/bank-account-groups`
5. Add/remove members via the `/accounts` sub-resource - **not** via PUT on the group
6. `DELETE` on the group returns `409` if it is in use

---

## Error Reference

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

---

## OpenAPI Spec

- OpenAPI: `https://developer.kyriba.com/static/apis/bank-account-groups/bank-account-groups.yaml`