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.

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. See 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).