POST
/
accounts
/
{accountId}
/
account-numbers
Create account number.
curl --request POST \
  --url https://sandbox.api.openfx.com/v1/accounts/{accountId}/account-numbers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Signature: <api-key>' \
  --header 'X-Timestamp: <api-key>' \
  --data '
{
  "type": "us_ach",
  "autoConvert": {
    "enabled": true,
    "convertToCurrency": "USD"
  }
}
'
{
  "id": "an_01953e1a5f4b7200",
  "accountId": "acc_01953e1a5f4b7002",
  "type": "us_ach",
  "status": "active",
  "routingNumber": "021000021",
  "accountNumberLast4": "7890",
  "createdAt": "2026-02-23T12:00:00Z"
}

Authorizations

​
Authorization
string
header
required

API key issued at onboarding. Passed as a Bearer token in the Authorization header: Authorization: Bearer <api-key>. Identifies the caller and determines organization scope. Invalid or revoked keys return 401 with error type authentication_error.

​
X-Signature
string
header
required

Ed25519 or RSA-SHA256 asymmetric signature over the request payload (ADR-0015). Provides request integrity and non-repudiation. The signature covers the HTTP method, path, query string, request body, and timestamp. Invalid signatures return 401 with error type authentication_error.

​
X-Timestamp
string
header
required

Unix timestamp (seconds) of when the request was signed. Server rejects requests where the timestamp drifts beyond +/-60 seconds from server time to prevent replay attacks. Must match the timestamp used in the signature computation.

Headers

​
Idempotency-Key
string
required

Idempotency key for this request. UUID v4 recommended. Max 128 characters. 24-hour retention. Same key + same body replays original response with Idempotency-Replayed: true. Same key + different body returns 409 (code: duplicate_idempotency_key). Same key while the original request is still processing returns 409 with a Retry-After header (code: idempotency_key_in_flight).

Maximum string length: 128
Example:

"550e8400-e29b-41d4-a716-446655440000"

Path Parameters

​
accountId
string
required

Unique identifier of the account (acc_ prefix). Account resource identifier.

Pattern: ^acc_[A-Za-z0-9]+$
Example:

"acc_01953e1a5f4b7002"

Body

application/json
​
type
enum<string>
required

Type of account number / deposit rail. (MVP constraint: only US account number types are supported with Erebor.)

Available options:
us_ach,
us_fedwire
​
autoConvert
object
deprecated

Deprecated. Use Settlement Routes for configurable inbound fund handling. Setting autoConvert creates a single-step settlement route with a convert action.

Response

Account number created.

Writable account number sub-resource. Represents a deposit rail address (ACH routing, wire, IBAN, etc.) attached to an account.

​
id
string
required

Account number resource identifier.

Pattern: ^an_[A-Za-z0-9]+$
Example:

"an_01953e1a5f4b7200"

​
accountId
string
required

Account resource identifier.

Pattern: ^acc_[A-Za-z0-9]+$
Example:

"acc_01953e1a5f4b7002"

​
type
enum<string>
required

Type of account number / deposit rail. (MVP constraint: only US account number types are supported with Erebor.)

Available options:
us_ach,
us_fedwire
​
status
enum<string>
required

Status of an account number.

Available options:
active,
suspended,
closed
​
createdAt
string<date-time>
required

UTC timestamp in RFC 3339 / ISO 8601 format.

Example:

"2026-02-23T12:00:00Z"

​
routingNumber
string

ABA routing number (US ACH/wire).

Example:

"021000021"

​
accountNumberLast4
string

Masked account number (last 4 digits).

Pattern: ^[0-9]{4}$
​
iban
string

Full IBAN (international bank account number).

Example:

"GB29NWBK60161331926819"

​
bic
string

SWIFT/BIC code.

Example:

"NWBKGB2L"

​
sortCode
string

UK sort code.

Example:

"601613"

​
bankName
string

Name of the bank.

​
autoConvert
object
deprecated

Deprecated. Use Settlement Routes for configurable inbound fund handling. Setting autoConvert creates a single-step settlement route with a convert action.