---
name: bank-branches
description: >
  Instructs AI agents how to create, read, update, and delete bank branches
  in Kyriba. A branch belongs to a bank and is a prerequisite for creating
  bank accounts.
version: 1.0.0
scopes:
  - bank-branch-scope
authors:
  - kyriba
tags:
  - kyriba
  - platform
  - bank-branches
  - 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 Branches

---

## Required Kyriba Permission

```
bank-branch-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 branch must belong to a bank (`bank.code` or `bank.uuid` required on create). A branch must exist before creating bank accounts.

---

## Base Path

```
/v1/bank-branches
```

---

## Endpoints

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

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

---

## Filterable & Sortable Fields

```
code, uuid, description, bank.code, bank.uuid,
address.country.code, address.country.uuid, bic
```

---

## Example Requests

**List branches for a bank:**
```
GET /v1/bank-branches?filter=bank.code==BNP_PARIS&sort=code
```

**Find branches by country:**
```
GET /v1/bank-branches?filter=address.country.code==FR
```

**Find branch by BIC:**
```
GET /v1/bank-branches?filter=bic==BNPAFRPP
```

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

{ "refs": ["BNP_PARIS_01", "CITI_NY_01"] }
```

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

**List response:**
```json
{
  "metadata": { "total": 2, "count": 2, "limit": 100, "offset": 0 },
  "results": [
    {
      "code": "BNP_PARIS_01",
      "uuid": "...",
      "bic": "BNPPFR33",
      "bank": { "code": "BNP_PARIS", "uuid": "..." },
      "address": {
        "country": { "code": "FR", "uuid": "..." },
        "city": null
      }
    }
  ]
}
```

>  Filtering by a non-existent `bank.code` returns an **empty list** (`200 + []`), not a `404`. If zero results are returned, verify the bank exists with `GET /v1/banks/{code}`.

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

{
  "code": "BNP_PARIS_01",
  "bank": { "code": "BNP_PARIS" },
  "bic": "BNPAFRPP",
  "address": { "country": { "code": "FR" }, "city": "Paris" }
}
```

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

---

## Key Fields

| Field | Description |
|---|---|
| `code` | Unique branch code |
| `uuid` | System-generated identifier |
| `bank` | Parent bank `{ "code": "...", "uuid": "..." }` - **required on create** |
| `bic` | SWIFT BIC code of this branch. **Can be `null`**. |
| `address.country` | `{ "code": "ISO2" }` - required on create |
| `address.city` | City. **Can be `null`**. |
| `idOfApplication` | SwiftNet ID of application (InterAct) |
| `interactServiceName` | Swift InterAct service name |

---

## Critical Rules

1. `bank` is **required** on create - a branch must belong to a bank
2. `uuid` is auto-generated - do not include in POST body
3. A branch cannot be deleted if accounts reference it (`409`)
4. Use `POST /v1/bank-branches/details` for bulk retrieval - returns `207`
5. Uniqueness enforced on `code`

---

## 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` | Branch not found |
| `409` | Code already exists or branch in use |

---

## OpenAPI Spec & Postman Collection

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