---
name: cash-balances
description: >
  Instructs AI agents how to retrieve cash balances from Kyriba. Supports
  single-account balance retrieval and multi-account aggregation by company,
  currency, country, or other entity groupings. Cash balances are computed
  from reconciled cash flows.
version: 1.0.0
scopes:
  - cash-balances-scope
authors:
  - kyriba
tags:
  - kyriba
  - liquidity
  - cash-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: Cash Balances

---

## Required Kyriba Permission

```
cash-balances-scope
```

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

---

## What are Cash Balances?

Cash balances are computed by Kyriba based on cash flows. For the same account and date, different balances are available depending on:
- **Date type:** `TRANSACTION` or `VALUE`
- **Cash flow status included:** actual, intraday, confirmed forecasts, estimated forecasts

>  Cash balances only include bank transactions successfully reconciled by the Cash Reconciliation process.

---

## Base Path

```
/v1/cash-balances
```

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/cash-balances/accounts/{ref}/balances` | Get balance for a single account by uuid or code |
| `GET` | `/v1/cash-balances/accounts/statementIdentifier={id}/balances` | Get balance by bank statement identifier |
| `POST` | `/v1/cash-balances/aggregation` | Get aggregated balances across multiple accounts |

---

## Single Account Balance

**Required query parameters:**
- `dateType` - `TRANSACTION` or `VALUE` (**required**)
- `startDate` - ISO date `YYYY-MM-DD` (**required**)
- `endDate` - ISO date `YYYY-MM-DD` (**required**)

**Optional:** `actual`, `intraday`, `confirmedForecasts`, `estimatedForecasts` (booleans)

**Example:**
```
GET /v1/cash-balances/accounts/MY_ACCOUNT/balances
    ?dateType=VALUE&startDate=2025-01-01&endDate=2025-01-31&actual=true
```

**Response:**
```json
{
  "account": { "code": "MY_ACCOUNT", "uuid": "..." },
  "cashBalance": [
    {
      "amount": -50000,
      "balanceDate": { "date": "2025-01-15", "dateType": "TRANSACTION" },
      "currencyCode": "EUR"
    }
  ]
}
```

---

## Aggregation - Multiple Accounts in One Call

>  Use this instead of looping over individual accounts.

```http
POST /v1/cash-balances/aggregation
Content-Type: application/json

{
  "accountType": "ALL",
  "cashFlowStatus": {
    "actual": true,
    "confirmedForecasts": true,
    "estimatedForecasts": true,
    "intraday": true
  },
  "currencyConversion": {
    "currency": { "code": "EUR" },
    "currencyRate": { "fixingDate": "2025-01-15", "mode": "FIXING" }
  },
  "datePeriod": {
    "dateType": "TRANSACTION",
    "startDate": "2025-01-15",
    "endDate": "2025-01-15"
  },
  "displayEntity": "ACCOUNT",
  "entities": [{ "code": "EUR" }],
  "entityType": "CURRENCY"
}
```

**`displayEntity` controls the grouping of results:**

| Value | Returns | Use when |
|---|---|---|
| `CURRENCY` | One aggregated row per target currency | You want a single total (e.g. total EUR position) |
| `ACCOUNT` | One row per account | You need per-account breakdown (sum client-side for total) |
| `COMPANY` | One row per company | You need company-level grouping |
| `COUNTRY` | One row per country | You need country-level grouping |

**`entityType`** - how to filter accounts: `CURRENCY`, `COMPANY`, `COUNTRY`
**`entities`** - list of `{ "code": "..." }` to filter by

**Aggregation response:**
```json
{
  "currency": { "code": "EUR" },
  "dateType": "TRANSACTION",
  "entities": [
    {
      "displayEntity": { "code": "BNP_EUR_338" },
      "balances": [{ "date": "2025-01-15", "amount": 337098588.845 }]
    }
  ]
}
```

>  Aggregation returns balances in **one designated currency** (`currencyConversion`).
> To get native currencies, submit one request per currency.

---

## Critical Rules

1. `dateType`, `startDate`, `endDate` are **required** on all endpoints
2. Use `displayEntity=CURRENCY` for a single aggregated total - `displayEntity=ACCOUNT` returns one row per account (sum client-side)
3. Cash balances only reflect **reconciled** transactions
4. For bulk retrieval, always use aggregation - individual account calls exhaust daily quota fast

---

## Error Reference

| Status | Meaning |
|---|---|
| `400` | Missing required params (`dateType`, `startDate`, `endDate`) |
| `403` | Required Kyriba permission not configured on your API client |
| `404` | Account not found for given `{ref}` |
| `415` | Wrong Content-Type on aggregation (must be `application/json`) |

---

## OpenAPI Spec & Postman Collection

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