HIFI Docs

External Account is v3’s bank-account resource — the destination for an Offramp payout or the source for an ACH-pull Onramp. Its v2 predecessor is POST /users/:userId/accounts. There are two big changes: identity moved out into a separate Counter Party resource — this page only covers the bank-detail fields that stayed behind — and the type field v2 used to identify a bank account’s country/rail (us, brazilGlobalNetwork, italyGlobalNetwork, and dozens of other per-country *GlobalNetwork values) is gone. v3 has no type field at all: HIFI derives the rail automatically from currency + bankAddress.country + transferType, combined with the counterparty’s KYC/KYB profile. See the platform-wide changes for ID format, pagination, error shape, and idempotency.

Endpoints

v2	v3	Notes
`POST /v2/users/:userId/accounts`	`POST /v3/external-accounts`	Nested by user → flat, top-level. Identity (`accountHolder`) split out to a separate `counterPartyId` — see below.
`GET /v2/users/:userId/accounts/:accountId`	`GET /v3/external-accounts/:externalAccountId`	Response shape changed — see below.
`GET /v2/users/:userId/accounts`	`GET /v3/external-accounts`	`userId` and `counterPartyId` are now optional query filters instead of a required path segment. List envelope changed to the standard `{data, pagination}` shape.
`DELETE /v2/users/:userId/accounts/:accountId`	`DELETE /v3/external-accounts/:externalAccountId`	Same deactivate semantics.
(none)	`PATCH /v3/external-accounts/:externalAccountId`	New — v2 had no way to update an existing account’s bank details.

Request changes: create an external account

v2 nested bank details under a key named after the country/rail type, alongside the embedded accountHolder:

{
  "userId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "type": "us",
  "accountHolder": { "...": "..." },
  "us": {
    "transferType": "ach",
    "accountNumber": "000123456789",
    "routingNumber": "021000021",
    "bankName": "Example Bank",
    "accountType": "Checking",
    "currency": "usd"
  }
}

v3 references a pre-created Counter Party instead of embedding identity, and uses one flat schema selected by country + currency + transfer type rather than a dynamic type-named key:

{
  "counterPartyId": "cpty_QW1e2r3t4y",
  "bankName": "Example Bank",
  "bankAddress": { "city": "New York", "stateProvinceRegion": "NY", "postalCode": "10001", "country": "US" },
  "currency": "USD",
  "transferType": "ACH",
  "accountNumber": "000123456789",
  "routingNumber": "021000021",
  "accountType": "CHECKING"
}

v2 field	v3 field	Change
`accountHolder`	`counterPartyId`	Removed as an embedded object — identity now lives on a separate Counter Party record, referenced by ID
`type` (`us`, `brazilGlobalNetwork`, `italyGlobalNetwork`, etc. — one value per country/rail family, plus the fields nested under a same-named key like `us: {...}`)	—	Removed. No `type` field, and no dynamic wrapper key — bank fields are flat on the request body. HIFI selects the rail automatically from `bankAddress.country` + `currency` + `transferType`, together with the counterparty’s KYC/KYB profile, instead of you specifying it via `type`.
`transferType`, `accountType`	`transferType`, `accountType`	Same names; uppercase enums now (`"ACH"`, `"CHECKING"`) instead of lowercase/mixed case (`"ach"`, `"Checking"`)
Non-US rail fields nested under their own `type` key (`iban`/`swiftCode`, `pix`, etc.)	Flat fields selected by `(bankAddress.country, currency, transferType)`	Not every combination is supported — an unsupported one is rejected with a validation error. E.g. PIX now requires exactly one of `pixKey`/`email`/`phoneNumber`/`cpf`/`cnpj`.

See Account Information for the exact field requirements per (bankAddress.country, currency, transferType) combination.

Response changes

v2 (GET /v2/users/:userId/accounts/:accountId) — fields returned in the clear, and identity/bank details duplicated three ways: top-level beneficiary*/accountOwner* fields, an embedded accountHolder object, and again inside a rail-specific sub-object (us here):

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "accountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "userId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "accountHolder": { "type": "individual", "name": "Jane Doe", "address": { "...": "..." } },
  "accountNumber": "000123456789",
  "routingNumber": "021000021",
  "bankName": "Example Bank",
  "beneficiaryName": "Jane Doe",
  "currency": "usd",
  "accountOwnerName": "Jane Doe",
  "accountOwnerType": "individual",
  "accountType": "us",
  "type": "us",
  "beneficiaryStreetLine1": "...", "beneficiaryCity": "...", "beneficiaryState": "...", "beneficiaryPostalCode": "...", "beneficiaryCountry": "...",
  "us": {
    "accountType": "Checking",
    "accountNumber": "000123456789",
    "routingNumber": "021000021",
    "iban": null,
    "swiftCode": null,
    "bankName": "Example Bank",
    "bankCountry": null,
    "bankAddress": null,
    "currency": "usd"
  },
  "isValid": true,
  "reason": null,
  "rail": { "currency": "usd", "railType": "offramp", "paymentRail": "rtp" }
}

v3 (GET /v3/external-accounts/:externalAccountId), consistent shape across every country/rail, with sensitive fields masked by default:

{
  "id": "extacct_QW1e2r3t4y",
  "userId": "usr_a1B2c3D4e5F6g7H8i9J0k",
  "counterPartyId": "cpty_QW1e2r3t4y",
  "accountNumber": "****6789",
  "routingNumber": "021000021",
  "accountType": "CHECKING",
  "bankName": "Example Bank",
  "bankAddress": { "city": "New York", "stateProvinceRegion": "NY", "postalCode": "10001", "country": "US" },
  "currency": "USD",
  "transferType": "ACH",
  "nickname": null,
  "status": "ACTIVE",
  "createdAt": "...",
  "updatedAt": "..."
}

Change	Detail
Field duplication	Removed. v2 repeated the same identity/bank details up to three times (top-level `beneficiary`/`accountOwner` fields, embedded `accountHolder`, and again inside the rail-specific `us`/etc. sub-object). v3 has one flat set of fields, no duplication.
`type` / top-level `accountType` (e.g. both `"us"`)	Removed. The v2 rail-family/country selector is gone — see the `type` row in Request changes above. The rail itself now surfaces as `transferType`; v3’s `accountType` instead means the bank account type (`"CHECKING"`, moved up from the nested `us.accountType` in v2).
`rail` (`currency`, `railType`, `paymentRail`)	Removed. Also a known quirk in v2: `railType` here returns `"offramp"` rather than an actual rail name, and `paymentRail` (`"rtp"`) doesn’t match the account’s own `us.accountType`/`type` — this object wasn’t reliable in v2 either.
`accountId`	Removed. Duplicated `id` in v2; v3 only has `id`.
`id`, `userId`	Raw UUIDs → prefixed public IDs (`extacct_...`, `usr_...`).
Sensitive fields masked	`accountNumber`, `iban`, `pixKey`, `phoneNumber`, `email`, `cpf`, `cnpj`, `fpsId`, and `clabe` are masked by default in v3 responses (e.g. `"****6789"`) — v2 returned these fields in the clear.
`counterPartyId`	New — resolves to the associated Counter Party record.
`isValid`, `reason`	Removed. No v3 equivalent on the External Account object.

List (GET /external-accounts): v2 returned { count, banks: [...], nextCursor } where nextCursor was a raw timestamp. v3 returns the standard { data, pagination } envelope — see platform-wide changes.

Status

ACTIVE / INACTIVE on both sides — same two-state model, just formalized as an explicit enum in v3.

ID format

Raw UUID in v2 → extacct_... prefixed public ID in v3.

​Endpoints

​Request changes: create an external account

​Response changes

​Status

​ID format

Endpoints

Request changes: create an external account

Response changes

Status

ID format