API Versioning

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:

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.

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.