---
name: bank-statement-balances
description: >
  Instructs AI agents how to retrieve bank statement balances from Kyriba.
  Bank statement balances are closing balances reported by banks via bank
  statements - distinct from cash balances computed from cash flows.
version: 1.0.0
scopes:
  - bank-balances-scope
authors:
  - kyriba
tags:
  - kyriba
  - liquidity
  - bank-statement-balances
  - 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 Statement Balances

---

## Required Kyriba Permission

```
bank-balances-scope
```

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

---

## What are Bank Statement Balances?

Bank statement balances are **closing balances as reported by the bank** in statement files (MT940, camt.053, etc.). They differ from Cash Balances (which are computed from cash flows):

- Only accounts with successfully received and quality-checked bank statements have balances here
- One account at a time - there is **no bulk or aggregation endpoint**
- For bulk retrieval use Cash Balances aggregation instead

---

## Base Path

```
/v1/bank-balances
```

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/bank-balances/accounts/{ref}/balances` | Get balance by Kyriba account uuid or code |
| `GET` | `/v1/bank-balances/accounts/statementIdentifier={id}/balances` | Get balance by external bank statement identifier |

---

## Required Parameters

Both endpoints require:
- `date` - balance date (`YYYY-MM-DD`) **required**
- `type` - balance type **required**

**`type` values:**

| Value | Description |
|---|---|
| `END_OF_DAY` | Closing balance at end of business day |
| `INTRADAY` | Intraday balance (if intraday statements are received) |

---

## Example Requests

**By Kyriba account code:**
```
GET /v1/bank-balances/accounts/MY_ACCOUNT/balances?date=2025-01-15&type=END_OF_DAY
```

**By Kyriba account uuid:**
```
GET /v1/bank-balances/accounts/c890b2e8-a5fa-413b-b53a-85729d16317b/balances?date=2025-01-15&type=END_OF_DAY
```

**By external bank statement identifier:**
```
GET /v1/bank-balances/accounts/statementIdentifier=FR7630006000011234567890189/balances?date=2025-01-15&type=END_OF_DAY
```

**Response:**
```json
{
  "account": {
    "code": "MY_ACCOUNT",
    "uuid": "c890b2e8-a5fa-413b-b53a-85729d16317b"
  },
  "bankBalance": {
    "amount": 250000.00,
    "currency": { "code": "EUR" },
    "date": "2025-01-15",
    "type": "END_OF_DAY"
  },
  "lastKnownBalanceDate": "2025-01-15"
}
```

> `lastKnownBalanceDate` - if no statement exists for the requested date, Kyriba searches back up to **31 days** for the most recent available balance and returns that date here.

---

## Critical Rules

1. **One account per request** - no bulk endpoint. For multiple accounts use Cash Balances aggregation
2. Both `date` and `type` are **required**
3. `lastKnownBalanceDate` may differ from requested `date` if no statement was received that day
4. Only accounts with valid, quality-checked bank statements return data - others return `404`

---

## When to Use vs Cash Balances

| Use Case | API |
|---|---|
| Closing balance as reported by bank | Bank Statement Balances |
| Computed position including forecasts | Cash Balances |
| Multiple accounts in one call | Cash Balances aggregation |
| Intraday position | Both (Cash Balances with `intraday=true`, or Bank Statement with `type=INTRADAY`) |

---

## Error Reference

| Status | Meaning |
|---|---|
| `200` | Success |
| `400` | Missing `date` or `type` parameter |
| `403` | Required Kyriba permission not configured on your API client |
| `404` | Account not found or no statement data available |

---

## OpenAPI Spec & Postman Collection

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