---
name: cash-flows
description: >
  Instructs AI agents how to create, read, update, and aggregate cash flows
  in Kyriba. Cash flows represent money movements (actual, forecast, intraday)
  linked to bank accounts. Supports CRUD operations and aggregation by entity.
version: 1.0.0
scopes:
  - cash-flows-scope
authors:
  - kyriba
tags:
  - kyriba
  - liquidity
  - cash-flows
  - 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 Flows

---

## Required Kyriba Permission

```
cash-flows-scope
```

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

---

## Base Path

```
/v1/cash-flows
```

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/cash-flows` | List cash flows (filtered by date and other criteria) |
| `POST` | `/v1/cash-flows` | Create a new cash flow |
| `POST` | `/v1/cash-flows/aggregation` | Get aggregated cash flows by entity |
| `PUT` | `/v1/cash-flows/{uuid}` | Update a specific cash flow |
| `DELETE` | `/v1/cash-flows/{uuid}` | Delete a specific cash flow |

>  **Do not delete cash flows** - once deleted they are permanently unavailable via API.
> Instead, change the `flowCode` to a dedicated "deleted" code (e.g., `+DELETED`).

---

## List Cash Flows

**Required:** `dateType` - `TRANSACTION`, `VALUE`, `ACCOUNTING`, `UPDATE`, or `CREATION`

**Example - confirmed and estimated flows for an account, next 30 days:**
```
GET /v1/cash-flows
    ?dateType=TRANSACTION
    &startDate=2025-04-01
    &endDate=2025-04-30
    &filter=account.code==MY_ACCOUNT;status=in=(CONFIRMED,ESTIMATED)
    &page.limit=100
```

**Example - reconciled bank transactions:**
```
GET /v1/cash-flows?dateType=TRANSACTION&startDate=2025-01-01&endDate=2025-01-31&filter=status==ACTUAL;actualMode==CASHREC
```

**List response:**
```json
{
  "metadata": { "total": 10, "count": 3, "limit": 3, "offset": 0 },
  "results": [
    {
      "uuid": "abc123",
      "flowCode": { "code": "+WIRE", "uuid": "..." },
      "budgetCode": { "code": "+WIRE", "uuid": "..." },
      "status": "CONFIRMED",
      "account": { "code": "MY_ACCOUNT", "uuid": "..." },
      "date": {
        "transactionDate": "2025-04-01",
        "valueDate": "2025-04-02",
        "accountingDate": "2025-04-03"
      },
      "flowAmount": { "amount": 10580.12, "currency": { "code": "EUR" } },
      "description": "Wire transfer",
      "reference": "REF-001"
    }
  ]
}
```

---

## Filterable Fields

```
account.uuid, account.code,
flowCode.uuid, flowCode.code,
budgetCode.uuid, budgetCode.code,
origin, description, reference,
status, actualMode, glStatus,
updateDateTime, flowId
```

**`status` values:** `ESTIMATED`, `CONFIRMED`, `ACTUAL`, `INTRADAY`

---

## Create a Cash Flow

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

{
  "account": { "code": "ACC001" },
  "flowCode": { "code": "+WIRE" },
  "status": "CONFIRMED",
  "date": {
    "transactionDate": "2025-04-01",
    "valueDate": "2025-04-02"
  },
  "flowAmount": { "currency": { "code": "EUR" }, "amount": 10580.12 },
  "reference": "REF-001"
}
```

**Response:** `{ "uuid": "abc123-..." }`

---

## Aggregation

>  `FLOW_CODE` is **not** a supported aggregation level. To group by flow code, list cash flows and group client-side.

Supported `aggregation.level` values: `ACCOUNT`, `COMPANY`, `COMPANY_GROUP`, `CURRENCY`, `COUNTRY`, `COUNTRY_GROUP`

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

{
  "currencyConversion": {
    "currency": { "code": "EUR" },
    "currencyRate": { "mode": "FIXING", "fixingDate": "2025-04-01" }
  },
  "filtering": {
    "entityFilters": [{ "entities": [{ "code": "ACC001" }], "entityType": "ACCOUNT" }],
    "accountType": "BANK",
    "period": { "dateType": "TRANSACTION", "startDate": "2025-04-01", "endDate": "2025-04-30" },
    "status": "CONFIRMED"
  },
  "aggregation": { "level1": "COMPANY", "level2": "CURRENCY", "level3": "ACCOUNT" }
}
```

---

## Critical Rules

1. `dateType` is **required** on `GET /v1/cash-flows`
2. **Do not delete cash flows** - change `flowCode` instead
3. `FLOW_CODE` is not an aggregation level - group by flow code client-side after listing
4. `signedAmount` is positive for inflows, negative for outflows
5. Reconciled bank transactions appear with `status=ACTUAL` and `actualMode=CASHREC`

---

## Error Reference

| Status | Meaning |
|---|---|
| `201` | Cash flow created - returns `{ "uuid": "..." }` |
| `400` | Missing `dateType` or invalid fields |
| `403` | Required Kyriba permission not configured on your API client |
| `409` | Uniqueness rule violated |
| `415` | Wrong Content-Type (must be `application/json`) |

---

## OpenAPI Spec & Postman Collection

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