---
updatedAt: 2026-10-13T20:59:18.000Z
agentTools:
  projectIndex: https://docs.cybrid.xyz/llms.txt
---

# API Versioning

How do I target a specific API version in my requests?

## Overview

API versioning allows Cybrid to evolve the platform without breaking existing integrations.

## Specify a version in API requests

Set the `Accept-Version` header to the desired version:

```bash
curl --request GET \
     --url https://bank.sandbox.cybrid.app/api/transfers \
     --header 'accept: application/json' \
     --header 'accept-version: 2025-06-01'
```

> ℹ️ Default version
>
> If the `Accept-Version` header is omitted, the API defaults to version `2022-01-01`.

## API version changelog

Each version introduces behavior changes to specific resources, listed below from oldest to newest.

### 2022-01-01

The baseline version. All existing behavior is unchanged when no version header is sent.

### 2025-06-01

Added the `holding` state to transfer `state`. Transfers in `holding` represent funds that are held (due to return risk) before processing.

* Backward compatibility: in `2022-01-01`, `holding` falls back to `pending`.

### 2025-10-01

Trade `state` now exposes a new `executed` state. In earlier versions, executed trades were returned as `pending` or `settling`.

* Filtering behavior change: in older versions, filtering `GET /api/trades?state=pending` or `GET /api/trades?state=settling` implicitly included executed trades. From `2025-10-01` onward, filtering is exact — pass `state=executed` to retrieve those records.

The `counterparty_bank_account` field (an object containing `routing_number_type`, `routing_number`, and `account_number`) for external bank accounts has been replaced by `counterparty_bank_account_details`, an array of bank account detail objects. This allows supplying multiple routing number formats in a single request (for example, ABA and SWIFT). This change applies only to `POST /api/external_bank_accounts` when `account_kind` is `raw_routing_details`.

> ⚠️ Breaking change for `raw_routing_details`
>
> Requests using `account_kind: raw_routing_details` must send `counterparty_bank_account_details` as an array instead of the former `counterparty_bank_account` object.

### 2025-12-01

Added the `reviewing` state to external wallet `state`. Wallets enter `reviewing` during compliance checks before being approved or failed.

* Backward compatibility: in versions before `2025-12-01`, `reviewing` falls back to `storing`.

### 2026-04-01

More granular transfer `failure_code` values are available. Older versions receive the coarser fallback value listed below.

| New code                        | Fallback (older versions) |
| ------------------------------- | ------------------------- |
| `daily_limit_exceeded`          | `limit_exceeded`          |
| `weekly_limit_exceeded`         | `limit_exceeded`          |
| `monthly_limit_exceeded`        | `limit_exceeded`          |
| `return_risk_exceeded`          | `compliance_rejection`    |
| `customer_contact_info_missing` | `invalid_destination`     |
| `recipient_cancelled`           | `external_vendor_error`   |

The `customer_contact_info_missing` and `recipient_cancelled` codes apply to e-transfer and EFT transfers. They provide more actionable detail than the generic codes they replace in older versions.

Added the `cancelling` state to transfer `state`, along with the Cancel Transfer operation `DELETE /api/transfers/{transfer_guid}`, which requests best-effort cancellation of an eligible `funding` transfer or `crypto` withdrawal. See [Cancel a Transfer](https://docs.cybrid.xyz/docs/cancel-a-transfer).

* Backward compatibility: the `cancelling` state falls back to `pending` in versions before `2026-04-01`, and the Cancel Transfer operation is not available in those versions (it returns `404`).