​
What Are Account Numbers?

Account numbers are routing identifiers that allow external parties to send fiat deposits to an OpenFX account. They are sub-resources of accounts, managed under /accounts/{accountId}/account-numbers. Each account number represents a deposit rail address — an ACH routing number pair, a Fedwire address, an IBAN, or a UK sort code. A single account can have multiple account numbers across different rails, enabling it to receive deposits from various payment networks. 
Account: acc_01953e1a5f4b7002 (USD)
  |-- an_... (us_ach)       -- Routing: 021000021, Acct: ****7890
  |-- an_... (us_fedwire)   -- Routing: 021000021, Acct: ****7890
  +-- an_... (iban)          -- GB29NWBK60161331926819
All account number IDs use the an_ prefix (e.g., an_01953e1a5f4b7200).

​
Account Number Types

TypeRailKey FieldsUse Case
us_achACH (US domestic)routingNumber, accountNumberUS domestic bank transfers
us_fedwireFedwire (US domestic)routingNumber, accountNumberSame-day US wire transfers
ibanSEPA / SWIFT (international)iban, bicEuropean and international transfers
uk_sort_codeFaster Payments / BACS (UK)sortCode, accountNumberUK domestic transfers
virtualVirtual account numberVariesPlatform-assigned virtual identifiers

​
Creating Account Numbers

​
US ACH Account Number

curl -X POST https://sandbox.api.openfx.com/v1/accounts/acc_01953e1a5f4b7002/account-numbers \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Signature: $SIGNATURE" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "us_ach"
  }'
Response: 
{
  "id": "an_01953e1a5f4b7200",
  "accountId": "acc_01953e1a5f4b7002",
  "type": "us_ach",
  "status": "active",
  "routingNumber": "021000021",
  "accountNumberLast4": "7890",
  "createdAt": "2026-02-23T12:00:00Z"
}

​
IBAN Account Number

curl -X POST https://sandbox.api.openfx.com/v1/accounts/acc_01953e1a5f4b7003/account-numbers \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Signature: $SIGNATURE" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "iban"
  }'
Response: 
{
  "id": "an_01953e1a5f4b7210",
  "accountId": "acc_01953e1a5f4b7003",
  "type": "iban",
  "status": "active",
  "iban": "GB29NWBK60161331926819",
  "bic": "NWBKGB2L",
  "bankName": "NatWest",
  "createdAt": "2026-02-23T12:00:00Z"
}

​
Sensitive Field Handling

Account numbers contain sensitive financial data. The API handles this with writeOnly and readOnly field semantics:
FieldAccessDescription
accountNumberwriteOnlyFull account number. Accepted in requests but never returned in responses.
accountNumberLast4readOnlyLast 4 digits of the account number. Returned in responses for identification.
The full accountNumber value is never returned in API responses. If you need the full account number (e.g., to share with a sender), you must capture it at the time of creation from your own records, or use the deposit instructions endpoint.
Other fields like routingNumber, iban, bic, and sortCode are returned in full because they are public routing identifiers, not sensitive account secrets.

​
Listing Account Numbers

Retrieve all account numbers for an account: 
curl -X GET https://sandbox.api.openfx.com/v1/accounts/acc_01953e1a5f4b7002/account-numbers \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Signature: $SIGNATURE" \
  -H "X-Timestamp: $TIMESTAMP"
The response uses the standard list envelope with cursor-based pagination: 
{
  "items": [
    {
      "id": "an_01953e1a5f4b7200",
      "accountId": "acc_01953e1a5f4b7002",
      "type": "us_ach",
      "status": "active",
      "routingNumber": "021000021",
      "accountNumberLast4": "7890",
      "createdAt": "2026-02-23T12:00:00Z"
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  }
}

​
Status Lifecycle

Account numbers follow a three-state lifecycle:
StatusDescription
activeAccount number is live and can receive deposits.
suspendedTemporarily disabled. Incoming deposits may be rejected or held.
closedPermanently deactivated. This is a terminal state.

​
Deposit Instructions

For a unified view of all deposit methods on an account (both account numbers and blockchain addresses), use the deposit instructions endpoint: 
curl -X GET https://sandbox.api.openfx.com/v1/accounts/acc_01953e1a5f4b7002/deposit-instructions \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Signature: $SIGNATURE" \
  -H "X-Timestamp: $TIMESTAMP"
Each deposit instruction includes a kind field (bank_account_number or blockchain_address) and the full details object of the underlying resource.
The deposit instructions endpoint is useful when building UI that shows all available deposit methods for an account in one place, without making separate calls to the account numbers and blockchain addresses endpoints.

​
API Reference