curl --request POST \
  --url https://production.hifi.com/v3/external-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "transferType": "ACH",
  "currency": "USD",
  "accountNumber": "123456789",
  "routingNumber": "021000021",
  "accountType": "CHECKING",
  "bankName": "Chase Bank",
  "bankAddress": {
    "addressLine1": "123 Main Street",
    "city": "New York",
    "stateProvinceRegion": "NY",
    "postalCode": "10001",
    "country": "USA"
  }
}
'

{
  "id": "extacct_9aB0xY4mNpXwZ7bV1aLdt",
  "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs",
  "counterPartyId": "cpty_7dLpR2mNpXwZ7bV1aQz3x",
  "accountNumber": "****6789",
  "routingNumber": "021000021",
  "accountType": "CHECKING",
  "bankName": "Chase Bank",
  "bankAddress": {
    "addressLine1": "123 Main Street",
    "city": "New York",
    "stateProvinceRegion": "NY",
    "postalCode": "10001",
    "country": "USA"
  },
  "currency": "USD",
  "transferType": "ACH",
  "status": "ACTIVE",
  "createdAt": "2026-07-01T10:30:00.000Z",
  "updatedAt": "2026-07-01T10:30:00.000Z"
}

{
  "type": "VALIDATION_ERROR",
  "message": "One or more fields are invalid or missing.",
  "fields": [
    {
      "code": "invalid_value",
      "message": "Must be a valid email address",
      "field": "email"
    }
  ]
}

{
  "type": "UNAUTHORIZED",
  "message": "Authentication required"
}

{
  "type": "RESOURCE_CONFLICT",
  "message": "Resource already exists or conflicts with current state"
}

{
  "type": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred"
}

External Accounts

Create an external account

Create a new external bank account for a counter party (identified by counterPartyId in the request body). External accounts represent beneficiary bank accounts where funds can be sent during offramp transfers.

Required fields vary by transferType, currency, and bankAddress.country. See the account information reference for supported combinations; unsupported combinations return a validation error. The counter party must be active.

POST

external-accounts

curl --request POST \
  --url https://production.hifi.com/v3/external-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "transferType": "ACH",
  "currency": "USD",
  "accountNumber": "123456789",
  "routingNumber": "021000021",
  "accountType": "CHECKING",
  "bankName": "Chase Bank",
  "bankAddress": {
    "addressLine1": "123 Main Street",
    "city": "New York",
    "stateProvinceRegion": "NY",
    "postalCode": "10001",
    "country": "USA"
  }
}
'

{
  "id": "extacct_9aB0xY4mNpXwZ7bV1aLdt",
  "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs",
  "counterPartyId": "cpty_7dLpR2mNpXwZ7bV1aQz3x",
  "accountNumber": "****6789",
  "routingNumber": "021000021",
  "accountType": "CHECKING",
  "bankName": "Chase Bank",
  "bankAddress": {
    "addressLine1": "123 Main Street",
    "city": "New York",
    "stateProvinceRegion": "NY",
    "postalCode": "10001",
    "country": "USA"
  },
  "currency": "USD",
  "transferType": "ACH",
  "status": "ACTIVE",
  "createdAt": "2026-07-01T10:30:00.000Z",
  "updatedAt": "2026-07-01T10:30:00.000Z"
}

{
  "type": "VALIDATION_ERROR",
  "message": "One or more fields are invalid or missing.",
  "fields": [
    {
      "code": "invalid_value",
      "message": "Must be a valid email address",
      "field": "email"
    }
  ]
}

{
  "type": "UNAUTHORIZED",
  "message": "Authentication required"
}

{
  "type": "RESOURCE_CONFLICT",
  "message": "Resource already exists or conflicts with current state"
}

{
  "type": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

External account details. Required fields vary by transferType, currency, and bankAddress.country. See the account information reference for the supported combinations and which fields each one requires.

counterPartyId

string

required

Public ID of the counter party this account belongs to (prefixed with cpty_).

Example:

"cpty_7dLpR2mNpXwZ7bV1aQz3x"

transferType

enum<string>

required

Available options:

ACH,

WIRE,

SWIFT,

RTP,

PIX,

SPEI,

CHATS,

FPS,

CIPS,

SEPA,

INSTAPAY,

PESONET,

NEQUI,

BANK

Example:

"ACH"

currency

enum<string>

required

Available options:

USD,

EUR,

BRL,

NGN,

KES,

TZS,

UGX,

BWP,

XAF,

MWK,

RWF,

ZMW,

XOF,

ZAR,

MXN,

PHP,

AED,

HKD,

CNY,

COP,

ARS,

SGD,

GBP,

AUD,

CAD,

JPY,

VND

Example:

"USD"

bankAddress

object

required

Address of the beneficiary bank. country is required for every rail; the other fields are required only for some rails — see the account information reference.

Show child attributes

nickname

string

Optional nickname for the external account.

Required string length: 1 - 100

bankName

string

Bank name. Required for most rails; not accepted for PIX.

Example:

"Chase Bank"

accountNumber

string

Bank account number.

Example:

"123456789"

routingNumber

string

ABA routing number (exactly 9 digits, ACH/WIRE/RTP only).

Example:

"021000021"

accountType

enum<string>

Available options:

CHECKING,

SAVINGS

Example:

"CHECKING"

iban

string

International Bank Account Number.

Example:

"DE91100000000123456789"

swiftCode

string

SWIFT/BIC code (8 or 11 characters).

Example:

"DEUTDEFF"

bankCode

string

Bank code (Hong Kong CHATS only).

Example:

"004"

fpsId

string

Faster Payment System identifier (Hong Kong FPS only).

Example:

"123456789"

clabe

string

CLABE number (Mexico SPEI only, exactly 18 digits).

Example:

"032180000118359719"

pixKey

string

PIX key, EVP (random key) format (Brazil PIX only).

Example:

"123e4567-e89b-12d3-a456-426614174000"

string

PIX key, email format (Brazil PIX only).

Example:

"jane.doe@example.com"

phoneNumber

string

PIX key (Brazil, E.164) or mobile money number (Colombia, E.164).

Example:

"+573001234567"

cpf

string

PIX key, CPF (individual taxpayer ID, 11 digits, Brazil PIX only).

Example:

"12345678901"

cnpj

string

PIX key, CNPJ (business taxpayer ID, 14 digits, Brazil PIX only).

Example:

"12345678901234"

Response

External account created successfully.

An external account.

string

Public ID of the external account (prefixed with extacct_).

Example:

"extacct_9aB0xY4mNpXwZ7bV1aLdt"

userId

string

Public ID of the user this account belongs to (prefixed with usr_).

Example:

"usr_3Kf9dQ2mNpXwZ7bV1aLcs"

counterPartyId

string

Public ID of the counter party this account belongs to (prefixed with cpty_).

Example:

"cpty_7dLpR2mNpXwZ7bV1aQz3x"

accountNumber

string

Masked bank account number.

Example:

"****6789"

routingNumber

string

ABA routing number.

Example:

"021000021"

accountType

enum<string>

Available options:

CHECKING,

SAVINGS

Example:

"CHECKING"

iban

string

Masked IBAN.

Example:

"****6789"

swiftCode

string

SWIFT/BIC code.

Example:

"DEUTDEFF"

sortCode

string

Sort code.

Example:

"123456"

pixKey

string

Masked PIX key (EVP format).

Example:

"****4000"

phoneNumber

string

Masked phone number.

Example:

"+57*****4567"

string

Masked email (PIX key, Brazil only).

Example:

"j***e@e*****e.com"

cpf

string

Masked CPF (PIX key, Brazil only).

Example:

"****8901"

cnpj

string

Masked CNPJ (PIX key, Brazil only).

Example:

"****1234"

bankName

string

Example:

"Chase Bank"

bankAddress

object

Address of the beneficiary bank.

Show child attributes

nickname

string | null

Client-supplied nickname for the external account.

Example:

"Primary settlement account"

currency

enum<string>

Available options:

USD,

EUR,

BRL,

NGN,

KES,

TZS,

UGX,

BWP,

XAF,

MWK,

RWF,

ZMW,

XOF,

ZAR,

MXN,

PHP,

AED,

HKD,

CNY,

COP,

ARS,

SGD,

GBP,

AUD,

CAD,

JPY,

VND

Example:

"USD"

transferType

enum<string>

Available options:

ACH,

WIRE,

SWIFT,

RTP,

PIX,

SPEI,

CHATS,

FPS,

CIPS,

SEPA,

INSTAPAY,

PESONET,

NEQUI,

BANK

Example:

"ACH"

fpsId

string

Masked Faster Payment System identifier.

Example:

"****6789"

clabe

string

Masked CLABE number.

Example:

"****9719"

status

enum<string>

Available options:

ACTIVE,

INACTIVE

Example:

"ACTIVE"

createdAt

string<date-time>

Example:

"2026-07-01T10:30:00.000Z"

updatedAt

string<date-time>

Example:

"2026-07-01T10:30:00.000Z"

⌘I

Overview

Endpoints

Create an external account

Authorizations

Body

Response