HIFI Docs

curl --request POST \
  --url https://production.hifi.com/v3/users/{userId}/counter-parties/{counterPartyId}/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"
}

POST

users

{userId}

counter-parties

{counterPartyId}

external-accounts

curl --request POST \
  --url https://production.hifi.com/v3/users/{userId}/counter-parties/{counterPartyId}/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.

Path Parameters

userId

string

required

ID of the user.

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

counterPartyId

string

required

Public ID of the counter party (prefixed with cpty_)

Body

application/json

External account details. The required fields depend on the combination of bankAddress.country, currency, and transferType. Only the combinations below are accepted; each row lists the rail-specific fields required in addition to currency, transferType, and bankAddress.

Transfer type	Currency	Country	Rail-specific required fields
ACH	USD	US	accountNumber, routingNumber, accountType, bankName
WIRE	USD	US	accountNumber, routingNumber, accountType, bankName
RTP	USD	US	accountNumber, routingNumber, accountType, bankName
SEPA	EUR	EUR-zone	iban, swiftCode, bankName
SWIFT	USD	58 countries (listed below)	swiftCode, accountNumber, bankName
SWIFT	USD	Indonesia (own field set)	accountNumber, swiftCode, bankName
PIX	BRL	Brazil	exactly one of: pixKey (EVP), email, phoneNumber, cpf, cnpj (bankName not accepted)
SPEI	MXN	Mexico	clabe, bankName
CIPS	CNY	China	accountNumber, bankName
CHATS	HKD	Hong Kong	accountNumber, bankCode, swiftCode, bankName
FPS	HKD	Hong Kong	accountNumber, fpsId, bankName
BANK	COP	Colombia	phoneNumber, bankName, accountType
NEQUI	COP	Colombia	phoneNumber, bankName
BANK	NGN	Nigeria	accountNumber, bankName
INSTAPAY	PHP	Philippines	accountNumber, bankName
PESONET	PHP	Philippines	accountNumber, bankName
BANK	SGD	Singapore	accountNumber, swiftCode, bankName
BANK	AED	United Arab Emirates (local)	iban, swiftCode, bankName

SWIFT (USD) supported bankAddress.country (ISO 3166-1 alpha-3): ARE, ARG, AUS, AUT, BEL, BRA, BGR, CAN, CHL, CHN, COL, HRV, CYP, CZE, DNK, EST, USA, FIN, FRA, DEU, GRC, HKG, HUN, ISL, IRL, ISR, IND, ITA, JPN, KEN, LVA, LIE, LTU, LUX, MAC, MLT, MEX, NLD, NZL, NGA, NOR, PAN, PHL, POL, PRT, ROU, SAU, SRB, SGP, SVK, SVN, ZAF, KOR, ESP, SWE, TWN, THA, TUR, GBR. Indonesia (IDN) uses a SWIFT variant with its own fields. United Arab Emirates also has a local AED rail (BANK, see above).

ACH account (US, USD).

transferType

enum<string>

required

Available options:

ACH

Example:

"ACH"

currency

enum<string>

required

Available options:

USD

Example:

"USD"

accountNumber

string

required

Bank account number.

Minimum string length: 1

Example:

"123456789"

routingNumber

string

required

ABA routing number (exactly 9 digits).

Required string length: 9

Example:

"021000021"

accountType

enum<string>

required

Available options:

CHECKING,

SAVINGS

Example:

"CHECKING"

bankName

string

required

Example:

"Chase Bank"

bankAddress

object

required

Address of the beneficiary bank.

Show child attributes

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

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

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

Path Parameters

Body

Response