---
name: currencies
description: >
  Instructs AI agents how to retrieve currency reference data from Kyriba.
  Currencies are read-only reference data used across bank accounts, cash flows,
  payments, and other financial entities.
version: 1.0.0
scopes:
  - currency-scope
authors:
  - kyriba
tags:
  - kyriba
  - risk
  - currencies
  - 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: Currencies

---

## Required Kyriba Permission

```
currency-scope
```

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

---

## Base Path

```
/v1/currencies
```

---

## Endpoints

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

> Currencies are **read-only** reference data. Create/update/delete is not supported via API.

---

## Filterable & Sortable Fields

```
uuid, code, description, reference, hideInList
```

---

## Example Requests

**List all currencies:**
```
GET /v1/currencies?page.limit=100&page.offset=0
```

**Get a specific currency by code:**
```
GET /v1/currencies?filter=code==EUR
```

**Get multiple currencies:**
```
GET /v1/currencies?filter=code=in=(EUR,USD,GBP)&sort=code
```

**Get visible ("active") currencies only:**
```
GET /v1/currencies?filter=hideInList==false&sort=code
```
> There is no `active` or `status` field on currencies. `hideInList==false` is the correct filter for currencies visible in the UI and usable in integrations.

**Get reference currency only:**
```
GET /v1/currencies?filter=reference==true
```

**Response:**
```json
{
  "metadata": {
    "links": { "current": "...", "next": "..." },
    "numberOfTotalResults": "<total count>",
    "pageLimit": 100,
    "pageOffset": 0,
    "pageResults": "<records in this page>"
  },
  "results": [
    {
      "code": "EUR",
      "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "description": "Euro",
      "deliveryFloat": 2,
      "numberOfDecimals": 2,
      "reference": true,
      "hideInList": false
    }
  ]
}
```

>  Currencies metadata uses different field names than other Kyriba APIs:
> `numberOfTotalResults` (not `total`), `pageLimit` (not `limit`), `pageOffset` (not `offset`), `pageResults` (not `count`).
> Handle both shapes defensively in code.
```

---

## Key Fields

| Field | Description |
|---|---|
| `code` | ISO 4217 3-letter currency code (e.g. `EUR`, `USD`) |
| `uuid` | System-generated unique identifier |
| `description` | Currency name |
| `deliveryFloat` | Default delivery float in days |
| `numberOfDecimals` | Default rounding decimal places |
| `reference` | `true` if this is the instance reference currency |
| `hideInList` | `true` if hidden from UI lookup lists |

---

## 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/currencies/currencies.yaml`
- Postman: `https://developer.kyriba.com/static/apis/currencies/currencies-postman-collection.json`