---
name: budget-codes
description: >
  Instructs AI agents how to retrieve budget codes from Kyriba.
  Budget codes represent business categories of cash movements and
  are used to structure cash position worksheets. They link to cash flow codes.
version: 1.0.0
scopes:
  - budget-code-scope
authors:
  - kyriba
tags:
  - kyriba
  - platform
  - liquidity
  - budget-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: Budget Codes

---

## Required Kyriba Permission

```
budget-code-scope
```

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

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

---

## What are Budget Codes?

Budget codes classify cash flows into business categories (e.g. operating, financial) for cash position reporting. Each cash flow code links to a budget code.

---

## Base Path

```
/v1/budget-codes
```

---

## Endpoints

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

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

---

## Filterable & Sortable Fields

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

---

## `type` Values

| Value | Direction |
|---|---|
| `OPERATING_COLLECTION` | Inflow |
| `OPERATING_DISBURSEMENT` | Outflow |
| `NON_OPERATING_COLLECTION` | Inflow |
| `NON_OPERATING_DISBURSEMENT` | Outflow |
| `FINANCIAL_COLLECTION` | Inflow |
| `FINANCIAL_DISBURSEMENT` | Outflow |

---

## Example Requests

**List all budget codes:**
```
GET /v1/budget-codes?page.limit=100&page.offset=0&sort=code
```

**Filter by type:**
```
GET /v1/budget-codes?filter=type==OPERATING_COLLECTION
```

**Get visible codes only:**
```
GET /v1/budget-codes?filter=hideInList==false
```

**Response:**
```json
{
  "metadata": { "total": 20, "count": 20, "limit": 100, "offset": 0 },
  "results": [
    {
      "code": "+WIRE",
      "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "description": "Incoming wire transfers",
      "type": "OPERATING_COLLECTION",
      "groupingCode": { "code": "COLLECTIONS", "uuid": "..." },
      "hideInList": false
    }
  ]
}
```

---

## Key Fields

| Field | Description |
|---|---|
| `code` | Budget code (max 10 chars) |
| `uuid` | System-generated identifier |
| `description` | Human-readable label. **Can be `null`**. |
| `type` | Cash flow direction category (see table above) |
| `groupingCode` | Parent grouping code `{ "code": "...", "uuid": "..." }`. **Can be `null`**. |
| `hideInList` | `true` if hidden from UI lookup lists |

---

## Relationship to Cash Flow Codes

Each cash flow code links to a budget code:
```json
{ "flowCode": { "code": "+WIRE" }, "budgetCode": { "code": "+WIRE" } }
```

Use this API to discover valid budget codes before creating cash flows or mapping tables.

---

## Error Reference

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

---

## OpenAPI Spec & Postman Collection

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