---
name: bank-groups
description: >
  Instructs AI agents how to create, read, update, and delete bank groups
  in Kyriba. Bank groups bundle multiple banks under a common reference,
  with optional counterparty and intermediary information.
version: 1.0.0
scopes:
  - bank-group-scope
authors:
  - kyriba
tags:
  - kyriba
  - platform
  - banks
  - 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 Groups

---

## Required Kyriba Permission

```
bank-group-scope
```

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

---

## What are Bank Groups?

Bank groups bundle multiple banks under a named group, optionally designating a leading bank and adding counterparty or intermediary contact information.

---

## Base URL

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

---

## Endpoints

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

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/bank-groups` | List bank groups |
| `POST` | `/api/v1/bank-groups` | Create a bank group |
| `GET` | `/api/v1/bank-groups/{ref}` | Get a specific bank group (includes `banks[]`) |
| `PUT` | `/api/v1/bank-groups/{ref}` | Update a bank group |
| `DELETE` | `/api/v1/bank-groups/{ref}` | Delete a bank group |

---

## Pagination

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

---

## Filterable Fields

```
code, description, hasCounterparty, hasIntermediary, leadingBank.code, leadingBank.uuid
```

---

## Key Fields

| Field | Description |
|---|---|
| `uuid` | System-generated identifier |
| `code` | Unique bank group code |
| `description` | Primary description. **Can be `null`**. |
| `description2` | Secondary description. **Can be `null`**. |
| `leadingBank` | Main bank of the group `{ "code": "...", "uuid": "..." }`. **Can be `null`**. |
| `banks[]` | Member banks - **only present in `GET /{ref}`**, not in list response |
| `hasCounterparty` | `true` if group has counterparty info |
| `hasIntermediary` | `true` if group has intermediary info |
| `contact` | Counterparty contact (only when `hasCounterparty = true`) |

---

## Example Requests

**List all bank groups:**
```
GET /api/v1/bank-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`.

**Filter groups with counterparty info:**
```
GET /api/v1/bank-groups?filter=hasCounterparty==true
```

**Get a group with its member banks:**
```
GET /api/v1/bank-groups/GROUP_BNPP
```

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

{
  "code": "GROUP_BNPP",
  "description": "BNP Paribas Group",
  "leadingBank": { "code": "BNPAFRPP" },
  "banks": [
    { "code": "BNPAFRPP" },
    { "code": "BNPAUSPP" }
  ]
}
```

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

---

## Critical Rules

1. `uuid` is auto-generated - do not include in POST body
2. `banks[]` is **absent from the list response** - always call `GET /{ref}` to retrieve member banks
3. `description` and `leadingBank` can be `null` - always use `or` / `get()` with a default
4. `DELETE` returns `409` if the group is in use - remove dependencies first

---

## Error Reference

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

---

## OpenAPI Spec

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