---
title: "Create an external account"
method: POST
path: "/v1/external-bank-accounts"
tags: ["External Bank Accounts"]
---

# Create an external account

`POST /v1/external-bank-accounts`

Create an external account for bank transfers or proxy-based payments.

If the same bank details or proxy alias match an account previously closed through the API, that account is reopened and its existing ID is returned. Fixed routes disabled when the account was closed remain disabled and must be re-enabled separately.

## Field Mapping

We use generic field names that adapt to country-specific identifiers:

| Field | US | UK | EU | India | Mexico | Australia |
|-------|----|----|----|----|----|----|
| `routingNumber` | ABA (9 digits) | Sort code (6 digits) | - | IFSC (11 chars) | - | BSB (6 digits) |
| `accountNumber` | Account number | Account (8 digits) | - | Account number | CLABE (18 digits) | Account number |
| `iban` | - | - | IBAN | - | - | - |

## Bank Account Requirements by Rail

| Rail | Required Fields |
|------|-----------------|
| **ACH/Wire** (US) | `routingNumber` + `accountNumber` |
| **SWIFT** (IBAN countries) | `swiftBic` + `iban` |
| **SWIFT** (US) | `swiftBic` + `accountNumber` (`routingNumber` optional) |
| **SWIFT** (AU) | `swiftBic` + `routingNumber` (BSB) + `accountNumber` |
| **SEPA** | `iban` (swiftBic optional) |
| **Faster Payments** (UK) | `routingNumber` (sort code) + `accountNumber` |
| **IMPS/NEFT** (India) | `routingNumber` (IFSC) + `accountNumber` |
| **SPEI** (Mexico) | `accountNumber` (18-digit CLABE) |

## Proxy Accounts

For instant payment rails (PIX, UPI, PromptPay), provide alias details instead of bank details:
- `aliasType`: phone, email, tax_id, national_id, or random
- `aliasValue`: The identifier value

The payment network resolves the alias to the recipient's account.

## Headers

- `X-API-Key` string

## Request body

- CreateExternalBankAccountDto
  - `correspondentBankName` string — Correspondent/intermediary bank name
  - `correspondentBankSwiftCode` string — Correspondent/intermediary bank SWIFT/BIC code (8 or 11 characters)
  - `correspondentAccountNumber` string — Correspondent/intermediary account number
  - `customerId` string, required — Customer ID
  - `counterpartyId` string — Existing counterparty ID. When provided for a third-party bank account, known counterparty data can be reused.
  - `beneficiaryName` string, required — Full legal name of the account holder
  - `paymentRails` string[], required — Payment rails this account supports. **Bank rails**: ACH, SWIFT, SEPA, WIRE, FASTER_PAYMENTS, IMPS, NEFT, SPEI, etc. **Proxy rails**: PIX, UPI, PROMPTPAY, DUITNOW (require aliasType + aliasValue) Compatible bank rails can be combined (e.g., a US account can support ["ach", "ach_same_day", "wire"]).
  - `beneficiaryType` 'INDIVIDUAL' | 'BUSINESS' — Beneficiary type (individual or business)
  - `isThirdParty` boolean — Whether the account holder differs from the customer (third-party payment). May require additional compliance checks.
  - `metadata` AccountMetadataDto
    - `nickname` string — Account nickname
    - `purpose` string — Account purpose
    - `tags` string[] — Account tags
  - `aliasType` 'PHONE' | 'EMAIL' | 'NATIONAL_ID' | 'TAX_ID' | 'RANDOM' | 'CORPORATE_ID' — **Required for proxy rails.** The type of alias identifier. Supported alias types vary by rail: - **PIX** (Brazil): phone, email, tax_id (CPF/CNPJ), random - **UPI** (India): phone, random (VPA) - **PromptPay** (Thailand): phone, national_id, tax_id - **DuitNow** (Malaysia): phone, national_id (NRIC), corporate_id - **GhIPSS** (Ghana): phone - **SINPE** (Costa Rica): phone **Note**: Both aliasType and aliasValue must be provided together.
  - `aliasValue` string — **Required for proxy rails.** The alias value. Format depends on aliasType: - **phone**: E.164 format (+5511912345678) - **email**: Standard email format - **tax_id**: Country-specific (Brazil CPF: 11 digits, CNPJ: 14 digits) - **national_id**: Country-specific (Thailand: 13 digits, Malaysia NRIC: 12 digits) - **random**: UUID format or provider-assigned key (e.g., UPI VPA like "user@upi") **Note**: Both aliasType and aliasValue must be provided together. **Normalization**: The value is normalized to lowercase and trimmed before storage. While some identifiers (e.g., UPI VPAs, emails) may display with mixed case, payment rails typically treat them as case-insensitive for routing.
  - `beneficiaryAddress` BeneficiaryAddressDto
    - `addressLine1` string, required — Street line 1. Maximum 35 characters for international wire compatibility. Do not include city, region, or postal code.
    - `addressLine2` string — Street line 2 (apartment, suite, etc.). Maximum 35 characters for international wire compatibility. Do not include city, region, or postal code.
    - `city` string, required — City
    - `state` string — State / Province
    - `postalCode` string, required — Postal code / ZIP code. May be empty for countries without a postal-code system, including the United Arab Emirates.
    - `country` string, required — Country code (ISO 3166-2)
    - `transliterated` TransliteratedAddressDto
      - `addressLine1` string — Transliterated address line 1 (Latin characters)
      - `addressLine2` string — Transliterated address line 2 (Latin characters)
      - `city` string — Transliterated city (Latin characters)
      - `state` string — Transliterated state/province (Latin characters)
  - `beneficiaryPhone` string — Beneficiary phone number in E.164 format
  - `beneficiaryDateOfBirth` string, date — Account holder's date of birth. Required at payout time for individual beneficiaries on supported corridors.
  - `bankName` string — Bank name. Auto-enriched from routing codes (SWIFT/BIC, IFSC, sort code, etc.) if not provided. Required if enrichment is unavailable.
  - `bankAddress` BankAddressDto
    - `addressLine1` string — Address line 1 (optional for bank addresses)
    - `addressLine2` string — Address line 2 (apartment, suite, etc.)
    - `city` string — City
    - `state` string — State / Province
    - `postalCode` string — Postal code / ZIP code (optional for bank addresses)
    - `country` string — Country code (ISO 3166-2)
  - `swiftBic` string — SWIFT/BIC code (8 or 11 characters). - **SWIFT transfers**: Always required - **SEPA**: Optional (IBAN-only supported)
  - `iban` string — IBAN (International Bank Account Number). - **SWIFT to EU/UK**: Required (with swiftBic) - **SEPA/SEPA Instant**: Required (swiftBic optional)
  - `accountNumber` string — Bank account number or equivalent. Usage varies by country: - **US** (ACH/Wire): Account number (with 9-digit routingNumber) - **UK** (Faster Payments): 8-digit account (with 6-digit sort code in routingNumber) - **India** (IMPS/NEFT): Account number (with 11 char IFSC in routingNumber) - **Mexico** (SPEI): 18-digit CLABE (routingNumber not needed) - **Argentina** (COELSA): 22-digit CBU (routingNumber not needed) - **Brazil** (TED): Account number (with bank code in routingNumber)
  - `routingNumber` string — Bank routing code. This field adapts to country-specific identifiers: - **US**: 9-digit ABA routing number - **CA**: 8-9 digits (transit + institution) - **AU**: 6-digit BSB - **UK**: 6-digit sort code - **India**: 11 character IFSC code
  - `branchCode` string — Bank branch code. Required for countries that use separate bank and branch identifiers: - **Japan**: 3-digit branch code (used with 4-digit bank code) - **Brazil**: 4-5 digit agency/branch number - **South Africa**: 6-digit branch code - **New Zealand**: 4-digit branch code - **Bolivia**: 3-letter branch city code (e.g. LPZ, SCZ)
  - `beneficiaryDocumentType` string — Type of the beneficiary's national/tax identification document. Required for payouts on rails whose clearing system carries the beneficiary document — the valid codes are rail-specific: - **Colombia (ACH)**: CC, NIT, CE, PA, PPT, TI, RC, TE, DIE, ND - **Chile (TEF)**: RUT, RUN, PAS, CE - **Paraguay (SIPAP)**: CI, PAS, CRP, CRC, RUC, DNI - **Peru (ACH)**: RUC, DNI, PAS, CE Brazil (TED) and Bolivia take only `beneficiaryDocumentNumber` (Brazil infers CPF vs CNPJ from the digit count). Optional at creation; payouts on these rails fail without it.
  - `beneficiaryDocumentNumber` string — The beneficiary's national/tax identification document number (e.g. CPF/CNPJ digits for Brazil, cédula number for Colombia/Paraguay, RUT for Chile). Format is validated per rail at payout time. Optional at creation; payouts on rails that require it fail without it.
  - `beneficiaryStateProvince` string — The beneficiary's state/department/province, for rails whose clearing system requires it on payouts (Peru ACH, e.g. LIMA). Optional at creation; payouts on those rails fail without it.
  - `bankAccountType` 'checking' | 'savings' — Bank account type (checking vs savings). Required for US ACH, and for payouts on rails whose clearing system carries it (e.g. Brazil TED, Colombia ACH, Chile TEF, Peru ACH) — accounts on those rails cannot receive payouts without it.
  - `currencyCodes` string[] — ISO 4217 currency codes this account can receive. If omitted, inferred from the payment rails. Can only be specified for Hong Kong (CHATS) or SWIFT payment rails.

## Response `201`

External account created, reused, or reopened successfully

- ExternalAccountResponseDto
  - `id` string, required — Account ID
  - `customerId` string, required — Customer ID
  - `counterpartyId` string, nullable — Counterparty ID when this is a third-party recipient account
  - `type` 'EXTERNAL_BANK' | 'EXTERNAL_PROXY', required — Account type
  - `status` 'IN_REVIEW' | 'ACTIVE' | 'CLOSED', required — Account status
  - `beneficiaryType` 'INDIVIDUAL' | 'BUSINESS', required — Beneficiary type
  - `beneficiaryName` string, required — Beneficiary name
  - `metadata` AccountMetadataDto
    - `nickname` string — Account nickname
    - `purpose` string — Account purpose
    - `tags` string[] — Account tags
  - `paymentRail` 'ACH' | 'ACH_SAME_DAY' | 'WIRE' | 'FEDWIRE' | 'FED_NOW' | 'RTP' | 'EREBOR' | 'EREBOR_RAIL' | 'BALANCE' | 'SWIFT' | 'SEPA' | 'SEPA_INSTANT' | 'TIPS' | 'FASTER_PAYMENTS' | 'BACS' | 'CHAPS' | 'ELIXIR' | 'NICS' | 'EFT' | 'INTERAC' | 'NPP' | 'BECS' | 'UPI' | 'IMPS' | 'IMPS_WITH_FIRC' | 'NEFT' | 'RTGS' | 'BI_FAST' | 'ARTAJASA' | 'PIX' | 'TED' | 'TEF' | 'SPEI' | 'COELSA' | 'SINPE' | 'CIPS' | 'CFXPS' | 'CHATS' | 'ZENGIN' | 'KFTC' | 'FAST_SG' | 'MEPS' | 'DUITNOW' | 'PROMPTPAY' | 'INSTAPAY' | 'PESONET' | 'NAPAS' | 'BEFTN' | 'SLIPS' | 'ZAHAV' | 'GHIPSS' | 'NIBSS' | 'PESALINK' | 'RTC_ZA' | 'TZS_RTGS' | 'EGP_ACH' | 'JOD_ACH' | 'NPSS' | 'MADA' | 'QPS' | 'DOP_ACH' | 'GTQ_ACH' | 'HNL_ACH' | 'PEN_ACH' | 'JMD_ACH' | 'USD_ACH_SV' | 'USD_ACH_EC' | 'CLP_TEF' | 'PSE' | 'COP_ACH' | 'BOB_RTGS' | 'PYG_ACH' | 'CERTIS' | 'DKK_TIPS' | 'SENT' | 'NKS' | 'BANKGIROT' | 'HKD_FPS' | 'IBFT' | 'TRY_FAST', required — Primary payment rail for this account
  - `paymentRails` string[] — All payment rails this account supports (bank accounts only)
  - `beneficiaryAddress` object, nullable — Beneficiary address (bank accounts only)
    - `addressLine1` string
    - `addressLine2` string
    - `city` string
    - `state` string
    - `postalCode` string
    - `country` string
  - `beneficiaryPhone` string, nullable — Beneficiary phone number
  - `beneficiaryDateOfBirth` string, date — Account holder's date of birth
  - `bankName` string, nullable — Bank name (bank accounts only)
  - `bankAddress` object, nullable — Bank address (bank accounts only)
    - `addressLine1` string
    - `addressLine2` string
    - `city` string
    - `state` string
    - `postalCode` string
    - `country` string
  - `swiftBic` string, nullable — SWIFT/BIC code (bank accounts only)
  - `iban` string, nullable — IBAN (bank accounts only)
  - `accountNumber` string, nullable — Bank account number (bank accounts only)
  - `routingNumber` string, nullable — Bank routing code (ABA routing number, sort code, BSB, IFSC, etc.)
  - `branchCode` string, nullable — Bank branch code (for countries like Japan, Brazil, South Africa that use separate branch identifiers)
  - `beneficiaryDocumentType` string — Type of the beneficiary's national/tax identification document (rail-specific codes, e.g. CC/NIT for Colombia, RUT for Chile)
  - `beneficiaryDocumentNumber` string — The beneficiary's national/tax identification document number
  - `beneficiaryStateProvince` string — The beneficiary's state/department/province (rails that require it on payouts, e.g. Peru ACH)
  - `correspondentBankName` string, nullable — Correspondent/intermediary bank name (SWIFT)
  - `correspondentBankSwiftCode` string, nullable — Correspondent/intermediary bank SWIFT/BIC code (SWIFT)
  - `correspondentAccountNumber` string, nullable — Correspondent/intermediary account number (SWIFT)
  - `bankAccountType` 'checking' | 'savings', nullable — Bank account type (bank accounts only)
  - `currencyCodes` string[], nullable — Supported currency codes
  - `aliasType` 'PHONE' | 'EMAIL' | 'NATIONAL_ID' | 'TAX_ID' | 'RANDOM' | 'CORPORATE_ID', nullable — Type of proxy alias (proxy accounts only)
  - `aliasValue` string, nullable — The proxy alias value (proxy accounts only)
  - `createdAt` string, date-time, required — Account creation date
  - `updatedAt` string, date-time, required — Account last update date
  - `created` boolean — Whether this account was newly created in this request or returned from an existing match

## Other responses

- `401` — Unauthorized - Invalid or missing authentication credentials

## Changes

- **2026-09-04** `7d6487f295d7` — 1 breaking, 1 warning
  - added `#/components/schemas/BeneficiaryAddressDto` to the `beneficiaryAddress` request property `allOf` list
  - removed `#/components/schemas/AddressDto` from the `beneficiaryAddress` request property `allOf` list

[Change history](https://skmtc.dev/infinite/apis/infinite-api/changes/v1/external-bank-accounts/post.md)

---

[API](https://skmtc.dev/infinite/apis/infinite-api.md) · [All operations](https://skmtc.dev/infinite/apis/infinite-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/infinite/infinite-api/revisions/70223aefae8c/schema)