---
name: cash-flow-codes
description: >
  Instructs AI agents how to retrieve cash flow codes from Kyriba.
  Cash flow codes classify cash flow transactions and determine their sign
  (inflow/outflow). They are required when creating cash flows.
version: 1.0.0
scopes:
  - cash-flow-code-scope
authors:
  - kyriba
tags:
  - kyriba
  - liquidity
  - cash-flow-codes
  - 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 Flow Codes

---

## Required Kyriba Permission

```
cash-flow-code-scope
```

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

>  Note: scope is `cash-flow-code-scope` (singular), not `cash-flow-codes-scope`.

---

## What are Cash Flow Codes?

Cash flow codes classify cash movements and **determine the sign** of cash flows:
- Codes prefixed with `+` = inflows (positive amounts)
- Codes prefixed with `-` = outflows (negative amounts)

They also link cash flows to budget codes for reporting.

---

## Base Path

```
/v1/cash-flow-codes
```

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/cash-flow-codes` | List cash flow codes (all or filtered) |

> Cash flow codes are **read-only** reference data. Create/update/delete is managed in the Kyriba UI.

---

## Filterable & Sortable Fields

```
code, uuid, description, type, budgetCode.code, budgetCode.uuid, hideInList
```

---

## Example Requests

**List all cash flow codes:**
```
GET /v1/cash-flow-codes?page.limit=100&page.offset=0
```

**Filter by code pattern:**
```
GET /v1/cash-flow-codes?filter=code==+WIRE*
```

**Get codes linked to a specific budget code:**
```
GET /v1/cash-flow-codes?filter=budgetCode.code==OPERATING
```

**Get codes by type:**
```
GET /v1/cash-flow-codes?filter=type==ACTUAL
```

**Response:**
```json
{
  "metadata": {
    "total": 50,
    "count": 50,
    "limit": 100,
    "offset": 0
  },
  "results": [
    {
      "code": "+WIRE",
      "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "description": "Incoming wire transfer",
      "type": "ACTUAL",
      "budgetCode": { "code": "+WIRE", "uuid": "..." },
      "hideInList": false
    }
  ]
}
```

---

## Key Fields

| Field | Description |
|---|---|
| `code` | Cash flow code (e.g. `+WIRE`, `-FEES`). Sign prefix determines inflow/outflow. Not all codes follow the `+`/`-` convention - some system codes have no prefix. |
| `uuid` | System-generated unique identifier |
| `description` | Human-readable label. **Can be `null`** - guard with `or ""` not just `.get("description", "")`. |
| `type` | Classification type. Known values: `COLLECTION`, `DISBURSEMENT`, `BALANCE_INITIALIZATION`, `ADJUSTMENT`, `INTERNAL_TRANSFER`. Additional values may exist per instance configuration. |
| `budgetCode` | Linked budget code (`{ "code": "...", "uuid": "..." }`). **Can be `null`**. |
| `hideInList` | `true` if hidden from UI lookup lists |

---

## Use in Cash Flows

When creating a cash flow, reference the code like this:
```json
{
  "flowCode": { "code": "+WIRE" },
  "budgetCode": { "code": "+WIRE" }
}
```

Use this API to discover valid codes before creating cash flows.

---

## Error Reference

| Status | Meaning |
|---|---|
| `200` | Success |
| `400` | Invalid filter expression |
| `403` | Required Kyriba permission not configured on your API client |

---

## OpenAPI Spec & Postman Collection

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