---
title: "Add an external account"
method: POST
path: "/external_accounts"
tags: ["External Accounts"]
---

# Add an external account

`POST /external_accounts`

Add an external account for a customer. The account will be created in an unverified state.

## Headers

- `Idempotency-Key` string

## Request body

- AddAccountsRequest
  - `account_identifiers` AddAccountsRequestAccountIdentifiers, required — The identifiers for the account. At least one of `number` or `iban` must be specified. Account number or IBAN can be specified for international accounts. For domestic accounts, only account number is required.
    - `iban` string — The IBAN of the account. On write, Synctera will store the entire IBAN number; on read, we only return the last 4 characters.
    - `number` string — The unique identifier of the account. On write, Synctera will store the entire account number; on read, we only return the last 4 characters.
  - `account_owner_names` string[], required — The names of the account owners.
  - `business_id` string, uuid — The identifier for the business customer associated with this external account. Exactly one of `business_id` or `customer_id` must be specified.
  - `currency` string — ISO 4217 alphabetic currency code
  - `customer_id` string, uuid — The identifier for the personal customer associated with this external account. Exactly one of `customer_id` or `business_id` must be specified.
  - `customer_type` 'BUSINESS' | 'PERSONAL', required — The type of customer in the external financial institution. _Not_ necessarily the customer type on Synctera's platform: a business customer might link to the owner's personal account at an external financial institution.
  - `metadata` object — User-supplied metadata
  - `nickname` string — A user-meaningful name for the account
  - `routing_identifiers` AddAccountsRequestRoutingIdentifiers, required
    - `ach_routing_number` string — The routing number used for US ACH payments.
    - `bank_countries` string[], required — The countries that this bank operates the account in
    - `bank_name` string, required — The name of the bank managing the account
    - `eft_ca_routing_number` string — > 🚧 Alpha > This is an Alpha property. Feedback from the community is welcome. We may make breaking changes to this property. The 9 digit routing number used for EFT CA payments, identifying a Canadian bank. The format is 0xxxyyyyy where xxx is the institution number and yyyyy is the transit number. On write, Synctera will store the entire routing number; on read, we only return the last 4 characters.
    - `international_wire_details` InternationalWireDetails
      - `bank_address` Address, required
        - `address_line_1` string, required — Street address line 1
        - `address_line_2` string — Street address line 2
        - `address_type` 'BILLING' | 'LEGAL' | 'OPERATING' | 'OTHER' | 'SHIPPING' — Specifies the address type.
        - `city` string — City
        - `country_code` string, required — ISO-3166-1 Alpha-2 country code
        - `id` string, uuid — The unique identifier for this resource.
        - `is_registered_agent` boolean — Indicates whether an address is a registered agent. Omitted if the address is not a registered agent.
        - `nickname` string — A nickname for the address. This is used to identify the address in the UI.
        - `postal_code` string — Postal code. For US, formats of 12345 or 12345-1234 are accepted. For CA, formats of A1A 1A1 or A1A1A1 (regardless of case) are accepted, and will be converted to A1A 1A1 format.
        - `state` string — State, region, province, or prefecture. This is the ISO-3166-2 subdivision code, excluding the country prefix. For example, TX for Texas USA or TAM for Tamaulipas Mexico. Its length varies by country, e.g. 2 characters for US, 3 for MX.
      - `correspondent_banks_details` CorrespondentBankDetails[] — Correspondent banks details used for international payments.
        - `bank_address` Address, required
          - `address_line_1` string, required — Street address line 1
          - `address_line_2` string — Street address line 2
          - `address_type` 'BILLING' | 'LEGAL' | 'OPERATING' | 'OTHER' | 'SHIPPING' — Specifies the address type.
          - `city` string — City
          - `country_code` string, required — ISO-3166-1 Alpha-2 country code
          - `id` string, uuid — The unique identifier for this resource.
          - `is_registered_agent` boolean — Indicates whether an address is a registered agent. Omitted if the address is not a registered agent.
          - `nickname` string — A nickname for the address. This is used to identify the address in the UI.
          - `postal_code` string — Postal code. For US, formats of 12345 or 12345-1234 are accepted. For CA, formats of A1A 1A1 or A1A1A1 (regardless of case) are accepted, and will be converted to A1A 1A1 format.
          - `state` string — State, region, province, or prefecture. This is the ISO-3166-2 subdivision code, excluding the country prefix. For example, TX for Texas USA or TAM for Tamaulipas Mexico. Its length varies by country, e.g. 2 characters for US, 3 for MX.
        - `bank_name` string, required — The name of the correspondent bank.
        - `swift_code` string, required — The SWIFT code (also known as BIC code) used for international payments.
      - `swift_code` string, required — The SWIFT code (also known as BIC code) used for international payments.
    - `network` 'ALGORAND' | 'AVALANCHE' | 'BITCOIN' | 'CARDANO' | 'CIRCLE' | 'EOS' | 'ETHEREUM' | 'OTHER' | 'POLKADOT' | 'SOLANA' | 'TRON' — The infrastructure or network governing the transfer of assets for your account.
    - `wire_routing_number` string — The routing number used for US domestic wire payments.
  - `tenant` string — The id of the tenant containing the resource. This is relevant for Fintechs that have multiple workspaces.
  - `type` 'CHECKING' | 'CRYPTO_WALLET' | 'OTHER_BANK_ACCOUNT' | 'SAVINGS' | 'WALLET', required — The type of the account
  - `vendor_account_id` string — The ID of the vendor account, will be empty for MANUAL vendor
  - `verification` union — Information about the account verification process. If the account has not been verified, this will be null.
    - BaseAccountVerification
      - `creation_time` string, date-time — The time at which verification was first completed.
      - `last_updated_time` string, date-time — The time at which verification was last updated.
      - `status` 'UNVERIFIED' | 'VERIFIED', required — The status of verification
      - `vendor` 'FINICITY' | 'MANUAL' | 'PLAID', required — The vendor used for verifying the account
    - BaseAccountVerification
      - `creation_time` string, date-time — The time at which verification was first completed.
      - `last_updated_time` string, date-time — The time at which verification was last updated.
      - `status` 'UNVERIFIED' | 'VERIFIED', required — The status of verification
      - `vendor` 'FINICITY' | 'MANUAL' | 'PLAID', required — The vendor used for verifying the account
    - BaseAccountVerification
      - `creation_time` string, date-time — The time at which verification was first completed.
      - `last_updated_time` string, date-time — The time at which verification was last updated.
      - `status` 'UNVERIFIED' | 'VERIFIED', required — The status of verification
      - `vendor` 'FINICITY' | 'MANUAL' | 'PLAID', required — The vendor used for verifying the account

## Response `201`

The external account added.

- ExternalAccount
  - `account_identifiers` AccountIdentifiers, required
    - `iban` string — The IBAN of the account. Value may be masked, in which case only the last four digits are returned.
    - `number` string, required — The unique identifier of the account. Value may be masked, in which case only the last four digits are returned.
  - `account_owner_names` string[], required — The names of the account owners. Values may be masked, in which case the array will be empty.
  - `business_id` string, uuid — The identifier for the business customer associated with this external account. Exactly one of `business_id` or `customer_id` will be returned.
  - `creation_time` string, date-time, required
  - `currency` string — ISO 4217 alphabetic currency code
  - `customer_id` string, uuid — The identifier for the personal customer associated with this external account. Exactly one of `customer_id` or `business_id` will be returned.
  - `deletion_time` string, date-time
  - `id` string, uuid, required — External account unique identifier
  - `last_updated_time` string, date-time, required
  - `metadata` object — User-supplied JSON format metadata.
  - `name` string — The official name of the account
  - `nickname` string, nullable — A user-meaningful name for the account
  - `routing_identifiers` AccountRouting, required
    - `ach_routing_number` string — The routing number used for US ACH payments. Only appears if `bank_countries` contains `US`. Value may be masked, in which case only the last four digits are returned.
    - `bank_address` Address
      - `address_line_1` string, required — Street address line 1
      - `address_line_2` string — Street address line 2
      - `address_type` 'BILLING' | 'LEGAL' | 'OPERATING' | 'OTHER' | 'SHIPPING' — Specifies the address type.
      - `city` string — City
      - `country_code` string, required — ISO-3166-1 Alpha-2 country code
      - `id` string, uuid — The unique identifier for this resource.
      - `is_registered_agent` boolean — Indicates whether an address is a registered agent. Omitted if the address is not a registered agent.
      - `nickname` string — A nickname for the address. This is used to identify the address in the UI.
      - `postal_code` string — Postal code. For US, formats of 12345 or 12345-1234 are accepted. For CA, formats of A1A 1A1 or A1A1A1 (regardless of case) are accepted, and will be converted to A1A 1A1 format.
      - `state` string — State, region, province, or prefecture. This is the ISO-3166-2 subdivision code, excluding the country prefix. For example, TX for Texas USA or TAM for Tamaulipas Mexico. Its length varies by country, e.g. 2 characters for US, 3 for MX.
    - `bank_countries` string[], required — The countries that this bank operates the account in
    - `bank_name` string, required — The name of the bank managing the account
    - `correspondent_bank_details` CorrespondentBankDetails[], nullable — The details of the correspondent banks for the account.
      - `bank_address` Address, required
        - `address_line_1` string, required — Street address line 1
        - `address_line_2` string — Street address line 2
        - `address_type` 'BILLING' | 'LEGAL' | 'OPERATING' | 'OTHER' | 'SHIPPING' — Specifies the address type.
        - `city` string — City
        - `country_code` string, required — ISO-3166-1 Alpha-2 country code
        - `id` string, uuid — The unique identifier for this resource.
        - `is_registered_agent` boolean — Indicates whether an address is a registered agent. Omitted if the address is not a registered agent.
        - `nickname` string — A nickname for the address. This is used to identify the address in the UI.
        - `postal_code` string — Postal code. For US, formats of 12345 or 12345-1234 are accepted. For CA, formats of A1A 1A1 or A1A1A1 (regardless of case) are accepted, and will be converted to A1A 1A1 format.
        - `state` string — State, region, province, or prefecture. This is the ISO-3166-2 subdivision code, excluding the country prefix. For example, TX for Texas USA or TAM for Tamaulipas Mexico. Its length varies by country, e.g. 2 characters for US, 3 for MX.
      - `bank_name` string, required — The name of the correspondent bank.
      - `swift_code` string, required — The SWIFT code (also known as BIC code) used for international payments.
    - `eft_ca_routing_number` string — > 🚧 Alpha > This is an Alpha property. Feedback from the community is welcome. We may make breaking changes to this property. The 9 digit routing number used for EFT CA payments, identifying a Canadian bank. The format is 0xxxyyyyy where xxx is the institution number and yyyyy is the transit number. On write, Synctera will store the entire routing number; on read, we only return the last 4 characters. Value may be masked, in which case only the last four digits are returned.
    - `eft_routing_number` string — The routing number used for EFT payments, identifying a Canadian bank, consisting of the institution number and the branch number. Only appears if `bank_countries` contains `CA`. Value may be masked, in which case only the last four digits are returned. This attribute is deprecated and will be removed in a future API version. Use eft_ca_routing_number instead.
    - `network` 'ALGORAND' | 'AVALANCHE' | 'BITCOIN' | 'CARDANO' | 'CIRCLE' | 'EOS' | 'ETHEREUM' | 'OTHER' | 'POLKADOT' | 'SOLANA' | 'TRON' — The infrastructure or network governing the transfer of assets for your account.
    - `swift_code` string — The SWIFT code for the bank. Value may be masked, in which case only the last four characters are returned.
    - `wire_routing_number` string — The routing number used for domestic wire payments. Only appears if `bank_countries` contains `US`. Value may be masked, in which case only the last four digits are returned.
  - `status` 'ACTIVE' | 'CLOSED' | 'DELETED' | 'INACTIVE', required — The current state of the account
  - `status_reason` string — The reason for the status for the external account.
  - `tenant` string — The id of the tenant containing the resource. This is relevant for Fintechs that have multiple workspaces.
  - `type` 'CHECKING' | 'CREDIT_CARD' | 'CRYPTO_WALLET' | 'INVESTMENT_529' | 'MONEY_MARKET' | 'OTHER' | 'OTHER_BANK_ACCOUNT' | 'SAVINGS' | 'WALLET', required — The type of the account
  - `vendor_data` ExternalAccountVendorData
    - `account_number_mask` string — The last alphanumeric characters of an account's official account number. Note that the mask may be non-unique between accounts, and it may also not match the mask that the bank displays to the user.
    - `institution_id` string — The ID of the institution external account belongs
  - `vendor_info` union — The information provided to Synctera from the vendor. Interpretation of this object is up to the client.
    - object
      - `content_type` 'application/json', required — Describes the content-type encoding received from the vendor
      - `json` object, required — Data representation in JSON
      - `vendor` string, required
    - object
      - `content_type` 'text/xml', required — Describes the content-type encoding received from the vendor
      - `vendor` string, required
      - `xml` string, required — Data representaion in XML
  - `verification` union, required — Information about the account verification process. If the account has not been verified, this will be null.
    - BaseAccountVerification
      - `creation_time` string, date-time — The time at which verification was first completed.
      - `last_updated_time` string, date-time — The time at which verification was last updated.
      - `status` 'UNVERIFIED' | 'VERIFIED', required — The status of verification
      - `vendor` 'FINICITY' | 'MANUAL' | 'PLAID', required — The vendor used for verifying the account
    - BaseAccountVerification
      - `creation_time` string, date-time — The time at which verification was first completed.
      - `last_updated_time` string, date-time — The time at which verification was last updated.
      - `status` 'UNVERIFIED' | 'VERIFIED', required — The status of verification
      - `vendor` 'FINICITY' | 'MANUAL' | 'PLAID', required — The vendor used for verifying the account
    - BaseAccountVerification
      - `creation_time` string, date-time — The time at which verification was first completed.
      - `last_updated_time` string, date-time — The time at which verification was last updated.
      - `status` 'UNVERIFIED' | 'VERIFIED', required — The status of verification
      - `vendor` 'FINICITY' | 'MANUAL' | 'PLAID', required — The vendor used for verifying the account

## Other responses

- `400` — BadRequest
- `401` — Unauthorized
- `403` — Forbidden error
- `409` — Resource already exists error
- `500` — Internal server error

---

[API](https://skmtc.net/synctera/apis/synctera-api.md) · [All operations](https://skmtc.net/synctera/apis/synctera-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/synctera/synctera-api/versions/b0d812e6cdd0/schema)