---
name: banks
description: >
  Instructs AI agents how to create, read, update, and delete banks in Kyriba.
  Banks are financial institutions linked to bank branches and accounts.
  Required before creating bank branches or bank accounts.
version: 1.0.0
scopes:
  - bank-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: Banks

---

## Required Kyriba Permission

```
bank-scope
```

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

---

## Entity Hierarchy

```
Bank -> Bank Branch -> Bank Account
```

A bank must exist before creating bank branches, and a branch must exist before creating accounts.

---

## Base Path

```
/v1/banks
```

---

## Endpoints

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

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/banks` | List banks |
| `POST` | `/v1/banks` | Create a new bank |
| `POST` | `/v1/banks/details` | Get full details for multiple banks by refs (bulk) |
| `GET` | `/v1/banks/{ref}` | Get a specific bank |
| `PUT` | `/v1/banks/{ref}` | Update a specific bank |
| `DELETE` | `/v1/banks/{ref}` | Delete a specific bank |

---

## Filterable & Sortable Fields

```
code, uuid, description, defaultGroup.uuid, defaultGroup.code,
countryCode, intercompany
```

---

## Example Requests

**List banks in France:**
```
GET /v1/banks?filter=countryCode==FR&sort=code&page.limit=100&page.offset=0
```

**Find intercompany banks:**
```
GET /v1/banks?filter=intercompany==true
```

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

{ "refs": ["BNP_PARIS", "CITI_NY", "a1b2c3d4-..."] }
```

**Bulk response (207):**
```json
{
  "results": [
    {
      "details": {
        "code": "BNP_PARIS",
        "uuid": "...",
        "bic": "BNPAFRPP",
        "description1": "BNP Paribas",
        "address": { "country": { "code": "FR" }, "city": "Paris" },
        "intercompany": false
      }
    }
  ]
}
```

**List response:**
```json
{
  "metadata": { "total": 27, "count": 27, "limit": 100, "offset": 0 },
  "results": [
    {
      "code": "BNP_PARIS",
      "uuid": "...",
      "bic": "BNPAFRPP",
      "description1": "BNP Paribas",
      "description2": null,
      "interfaceCode": "BNP",
      "address": { "country": { "code": "FR" }, "city": "Paris" },
      "intercompany": false,
      "defaultGroup": { "code": "FRENCH_BANKS", "uuid": "..." }
    }
  ]
}
```

>  `description1` and `description2` can be `null` (key present, value null). Guard with `value or ""` not just `.get("description1", "")`.
> Note: the filterable field is named `description` but the response object contains `description1` and `description2`.

**Create a bank:**
```http
POST /v1/banks
Content-Type: application/json

{
  "code": "BNP_PARIS",
  "bic": "BNPAFRPP",
  "description1": "BNP Paribas",
  "address": { "country": { "code": "FR" } }
}
```

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

---

## Key Fields

| Field | Description |
|---|---|
| `code` | Unique bank code (max 10 chars) |
| `uuid` | System-generated identifier |
| `bic` | SWIFT BIC code |
| `description1` | Primary bank name |
| `description2` | Secondary name |
| `interfaceCode` | Interface/routing code |
| `address.country` | `{ "code": "ISO2" }` - required on create |
| `intercompany` | `true` if this is an intercompany bank |
| `defaultGroup` | Default bank group `{ "code": "..." }` |
| `lei` | Legal Entity Identifier |

---

## Critical Rules

1. `uuid` is auto-generated - do not include in POST body
2. `address.country` is required on create
3. A bank cannot be deleted if it has branches or accounts referencing it (`409`)
4. Uniqueness enforced on `code` and `interfaceCode`
5. Use `POST /v1/banks/details` for bulk retrieval - returns `207` Multi-Status

---

## Error Reference

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

---

## OpenAPI Spec & Postman Collection

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