---
name: bank-accounts
description: >
  Instructs AI agents how to create, read, update, and delete bank accounts
  and inter-company accounts in Kyriba. Covers listing, filtering, bulk retrieval,
  and managing account settings including payment instructions and reconciliation options.
version: 1.0.0
scopes:
  - account-scope
authors:
  - kyriba
tags:
  - kyriba
  - platform
  - bank-accounts
  - 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: Bank Accounts

---

## Required Kyriba Permission

```
account-scope
```

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

---

## Base Path

```
/v1/accounts
```

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/accounts` | List accounts (all or filtered) |
| `POST` | `/v1/accounts` | Create a new account |
| `POST` | `/v1/accounts/details` | Get full details for multiple accounts by refs |
| `GET` | `/v1/accounts/{ref}` | Get a specific account by uuid or code |
| `PUT` | `/v1/accounts/{ref}` | Update a specific account |
| `DELETE` | `/v1/accounts/{ref}` | Delete a specific account |

`{ref}` accepts either `uuid` or `code`.

---

## Filterable & Sortable Fields

```
code, uuid, description, company.uuid, company.code,
branch.uuid, branch.code, bank.uuid, bank.code,
currency.uuid, currency.code, countryCode,
accountType, banCode, creationDate, updateDate,
closingDate, activeStatus, statementIdentifier,
accountAvailableForPayments
```

**`accountType` values:** `BANK_ACCOUNT`, `INTERCOMPANY_ACCOUNT`, `OTHER_ACCOUNT`, `SHARED_ACCOUNT`
**`activeStatus` values:** `OPENED`, `CLOSED`

---

## Example Requests

**List all open EUR accounts:**
```
GET /v1/accounts?filter=currency.code==EUR;activeStatus==OPENED&page.limit=100&page.offset=0
```

**GET list response:**
```json
{
  "metadata": {
    "pageLimit": 100,
    "pageOffset": 0,
    "pageResults": 2,
    "numberOfTotalResults": 2
  },
  "results": [ ... ]
}
```
> Response key is always `results`. Stop paginating when `len(results) < pageLimit`.

**List accounts for a specific company:**
```
GET /v1/accounts?filter=company.code==MY_COMPANY;activeStatus==OPENED
```

**Get account available for payments:**
```
GET /v1/accounts?filter=accountAvailableForPayments==true;currency.code==USD
```

**Get multiple accounts by refs (bulk):**
```http
POST /v1/accounts/details
Content-Type: application/json

{
  "refs": ["012CITIDKK", "c890b2e8-a5fa-413b-b53a-85729d16317b"]
}
```

**Create a new account:**
```http
POST /v1/accounts
Content-Type: application/json

{
  "code": "MY_ACCOUNT_001",
  "description": "Main EUR Account",
  "company": { "code": "MY_COMPANY" },
  "bankBranch": { "code": "BRANCH_CODE" },
  "currency": { "code": "EUR" },
  "countryCode": "FR",
  "accountType": "BANK_ACCOUNT",
  "activeStatus": "OPENED",
  "accountAvailableForPayments": true
}
```

**Create response:**
```json
{ "uuid": "c890b2e8-a5fa-413b-b53a-85729d16317b" }
```

**Update an account:**
```http
PUT /v1/accounts/{ref}
Content-Type: application/json

{
  "description": "Updated description",
  "activeStatus": "OPENED"
}
```

---

## Key Fields

| Field | Description |
|---|---|
| `code` | Unique account code (human-readable identifier) |
| `uuid` | System-generated unique identifier |
| `company` | Owning company (`{ "code": "..." }` or `{ "uuid": "..." }`) |
| `bank` | Associated bank (`{ "code": "BIC" }` or `{ "uuid": "..." }`) |
| `currency` | Account currency (`{ "code": "EUR" }`) |
| `accountType` | Type of account |
| `activeStatus` | `OPENED` or `CLOSED` |
| `statementIdentifier` | External bank identifier used in bank statements |
| `accountAvailableForPayments` | Whether the account can be used for payment initiation |
| `ibanCode` | IBAN. Can be `null` if not populated. |
| `banCode` | Local bank account number (non-IBAN format) |
| `statementIdentifier` | Identifier used in bank statement reconciliation — **not** the IBAN |

---

## Critical Rules

1. `uuid` is auto-generated - do not pass it in `POST` body
2. Identify accounts by `code` (human-readable) or `uuid` (system) interchangeably in `{ref}`
3. Use `POST /v1/accounts/details` for bulk retrieval - more efficient than N individual `GET` calls
4. Uniqueness is enforced on `code`
5. A `409 Conflict` on delete means the account is in use (linked to transactions or payments)
6. Use `bankBranch.code` (not `bank.code`) in the POST body — BIC codes identify banks, not branches. Look up the branch code first via `GET /v1/bank-branches`.

---

## Error Reference

| Status | Meaning |
|---|---|
| `201` | Account created - returns `{ "uuid": "..." }` |
| `400` | Bad request - invalid fields or missing required data |
| `401` | Authentication required or token expired |
| `403` | Required Kyriba permission not configured on your API client |
| `404` | Account not found for given `{ref}` |
| `409` | Conflict - code already exists or account is in use |
| `415` | Wrong Content-Type (must be `application/json`) |

---

## OpenAPI Spec & Postman Collection

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