Bridge External Accounts API

openapi: 3.0.2
info:
  title: Bridge API Keys External Accounts API
  description: APIs to move into, out of, and between any form of a dollar
  version: '1'
servers:
- url: https://api.bridge.xyz/v0
  description: The base path for all resources
security:
- ApiKey: []
tags:
- name: External Accounts
paths:
  /customers/{customerID}/external_accounts:
    parameters:
    - $ref: '#/components/parameters/CustomerIDParameter'
    get:
      summary: Get all External Accounts
      tags:
      - External Accounts
      description: Get all External Accounts for a passed in customer.
      parameters:
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/ExternalAccountStartingAfterParameter'
      - $ref: '#/components/parameters/ExternalAccountEndingBeforeParameter'
      responses:
        '200':
          description: List of External Accounts (the returned list is empty if no External Accounts exist)
          content:
            application/json:
              schema:
                title: ExternalAccount
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    minItems: 0
                    items:
                      $ref: '#/components/schemas/ExternalAccountResponse'
                  count:
                    description: total number of items in data
                    type: integer
              examples:
                ExternalAccountsFound:
                  summary: A non-empty list of External Accounts
                  value:
                    data:
                    - $ref: '#/components/examples/SuccessfulExternalAccountResponse/value'
                NoExternalAccountsFound:
                  summary: An empty list of External Accounts
                  value:
                    data: []
                    count: 0
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
    post:
      summary: Create a new External Account
      tags:
      - External Accounts
      description: '_Note_: If adding US external accounts, we recommend reading through the US Beneficiary Address Validation doc ([link](https://apidocs.bridge.xyz/docs/us-beneficiary-address-validation)) to avoid issues related to incorrect addresses.

        '
      parameters:
      - $ref: '#/components/parameters/IdempotencyKeyParameter'
      requestBody:
        description: New External Account object to be created
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExternalAccountInput'
            examples:
              ACH:
                $ref: '#/components/examples/CreateAchExternalAccountRequest'
              IBAN:
                $ref: '#/components/examples/CreateIbanExternalAccountRequest'
              SWIFT:
                $ref: '#/components/examples/CreateSwiftExternalAccountRequest'
              CLABE:
                $ref: '#/components/examples/CreateClabeExternalAccountRequest'
              Pix_Key:
                $ref: '#/components/examples/CreatePixExternalAccountRequest'
              Pix_BrCode:
                $ref: '#/components/examples/CreateBrCodeExternalAccountRequest'
              BreB:
                $ref: '#/components/examples/CreateBreBExternalAccountRequest'
              CO_Bank_Transfer:
                $ref: '#/components/examples/CreateCoBankTransferExternalAccountRequest'
      responses:
        '201':
          description: External Account object created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalAccountResponse'
              examples:
                ACH:
                  $ref: '#/components/examples/SuccessfulExternalAccountResponse'
                IBAN:
                  $ref: '#/components/examples/SuccessfulIbanExternalAccountResponse'
                SWIFT:
                  $ref: '#/components/examples/SuccessfulSwiftExternalAccountResponse'
                CLABE:
                  $ref: '#/components/examples/SuccessfulClabeExternalAccountResponse'
                Pix_Key:
                  $ref: '#/components/examples/SuccessfulPixKeyExternalAccountResponse'
                Pix_BrCode:
                  $ref: '#/components/examples/SuccessfulBrCodeExternalAccountResponse'
                BreB:
                  $ref: '#/components/examples/SuccessfulBreBExternalAccountResponse'
                CO_Bank_Transfer:
                  $ref: '#/components/examples/SuccessfulCoBankTransferExternalAccountResponse'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
  /customers/{customerID}/external_accounts/{externalAccountID}:
    parameters:
    - $ref: '#/components/parameters/CustomerIDParameter'
    - $ref: '#/components/parameters/ExternalAccountIDParameter'
    get:
      summary: Retrieve an External Account object
      description: Retrieve an External Account object (banks, debit cards etc) from the passed in customer ID and External Account ID
      tags:
      - External Accounts
      responses:
        '200':
          description: Successful External Account object response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalAccountResponse'
              examples:
                SuccessfulExternalAccountResponse:
                  $ref: '#/components/examples/SuccessfulExternalAccountResponse'
                SuccessfulIbanExternalAccountResponse:
                  $ref: '#/components/examples/SuccessfulIbanExternalAccountResponse'
                SuccessfulPixKeyExternalAccountResponse:
                  $ref: '#/components/examples/SuccessfulPixKeyExternalAccountResponse'
                SuccessfulBrCodeExternalAccountResponse:
                  $ref: '#/components/examples/SuccessfulBrCodeExternalAccountResponse'
                SuccessfulBreBExternalAccountResponse:
                  $ref: '#/components/examples/SuccessfulBreBExternalAccountResponse'
                SuccessfulCoBankTransferExternalAccountResponse:
                  $ref: '#/components/examples/SuccessfulCoBankTransferExternalAccountResponse'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
    put:
      summary: Update an External Account
      tags:
      - External Accounts
      requestBody:
        description: External Account details to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateExternalAccountInput'
      responses:
        '200':
          description: External Account object updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalAccountResponse'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '400':
          $ref: '#/components/responses/BadExternalAccountUpdateError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
    delete:
      summary: Delete a single External Account object
      tags:
      - External Accounts
      description: Delete an External Account object from the passed in External Account ID
      responses:
        '200':
          description: Successfully deleted External Account object response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalAccountResponse'
              examples:
                DeletedExternalAccountResponse:
                  $ref: '#/components/examples/SuccessfulExternalAccountResponse'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
  /customers/{customerID}/external_accounts/{externalAccountID}/deactivate:
    post:
      summary: Deactivate an External Account
      description: Deactivate an active External Account. The External Account is preserved and can be reactivated later via the reactivate endpoint.
      tags:
      - External Accounts
      parameters:
      - $ref: '#/components/parameters/IdempotencyKeyParameter'
      - $ref: '#/components/parameters/CustomerIDParameter'
      - $ref: '#/components/parameters/ExternalAccountIDParameter'
      responses:
        '200':
          description: Deactivated External Account object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalAccountResponse'
              examples:
                DeactivatedExternalAccountResponse:
                  $ref: '#/components/examples/SuccessfulExternalAccountResponse'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
  /customers/{customerID}/external_accounts/{externalAccountID}/verify:
    post:
      summary: Verify an External Account
      description: 'Trigger a verification check for an external account. Verifies that the `account_owner_name` matches the actual account holder at the receiving bank.


        Supported for `iban` (EUR) and `gb` (GBP) account types only. Does not require an Idempotency-Key header.


        After triggering, poll the external account''s `account_verification` field until `completed_at` is populated.

        '
      tags:
      - External Accounts
      parameters:
      - $ref: '#/components/parameters/CustomerIDParameter'
      - $ref: '#/components/parameters/ExternalAccountIDParameter'
      responses:
        '200':
          description: Verification initiated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  account_type:
                    type: string
                    enum:
                    - iban
                    - gb
                    description: The account type that was verified.
                  account_verification:
                    description: The current state of the verification.
                    type: object
                    properties:
                      iban:
                        type: object
                        description: Present when verifying an IBAN account.
                        properties:
                          match_level:
                            type: string
                            enum:
                            - pending
                            - match
                            - close_match
                            - no_match
                            - error
                            description: The result of the name match check.
                          reason_code:
                            type: string
                            nullable: true
                            description: Additional context from the receiving bank when the result is not a full match.
                          validated_account_owner_name:
                            type: string
                            nullable: true
                            description: The name on file at the receiving bank.
                      gb:
                        type: object
                        description: Present when verifying a GB account.
                        properties:
                          match_level:
                            type: string
                            enum:
                            - pending
                            - match
                            - close_match
                            - no_match
                            - error
                            description: The result of the name match check.
                          reason_code:
                            type: string
                            nullable: true
                            description: Additional context from the receiving bank when the result is not a full match.
                          validated_account_owner_name:
                            type: string
                            nullable: true
                            description: The name on file at the receiving bank.
                      requested_at:
                        type: string
                        format: date-time
                        description: When the verification was requested.
                      completed_at:
                        type: string
                        format: date-time
                        nullable: true
                        description: When the verification completed. Null while pending.
              examples:
                PendingIbanVerification:
                  summary: A newly triggered IBAN verification
                  value:
                    account_type: iban
                    account_verification:
                      iban:
                        match_level: pending
                        reason_code: null
                        validated_account_owner_name: null
                      requested_at: '2026-01-15T12:00:00.000Z'
                      completed_at: null
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: A verification is already in progress for this external account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/UnexpectedError'
  /customers/{customerID}/external_accounts/{externalAccountID}/reactivate:
    post:
      summary: Reactivate an External Account
      description: Reactivate a previously deactivated External Account
      tags:
      - External Accounts
      parameters:
      - $ref: '#/components/parameters/IdempotencyKeyParameter'
      - $ref: '#/components/parameters/CustomerIDParameter'
      - $ref: '#/components/parameters/ExternalAccountIDParameter'
      responses:
        '200':
          description: Reactivated External Account object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalAccountResponse'
        '400':
          $ref: '#/components/responses/BadExternalAccountReactivateError'
  /external_accounts:
    parameters:
    - $ref: '#/components/parameters/LimitParameter'
    - $ref: '#/components/parameters/ExternalAccountStartingAfterParameter'
    - $ref: '#/components/parameters/ExternalAccountEndingBeforeParameter'
    get:
      summary: Get all External Accounts
      tags:
      - External Accounts
      description: Get all External Accounts.
      responses:
        '200':
          description: List of External Accounts (the returned list is empty if no External Accounts exist)
          content:
            application/json:
              schema:
                title: ExternalAccount
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    minItems: 0
                    items:
                      $ref: '#/components/schemas/ExternalAccountResponse'
                  count:
                    description: total number of items in data
                    type: integer
              examples:
                ExternalAccountsFound:
                  summary: A non-empty list of External Accounts
                  value:
                    data:
                    - $ref: '#/components/examples/SuccessfulExternalAccountResponse/value'
                NoExternalAccountsFound:
                  summary: An empty list of External Accounts
                  value:
                    data: []
                    count: 0
components:
  schemas:
    ExternalAccountUnknown:
      title: SWIFT
      description: SWIFT international wire transfer (account_type `iban` or `unknown`)
      allOf:
      - $ref: '#/components/schemas/ExternalAccountBaseWithOwnerInfo'
      - type: object
        required:
        - account_type
        - currency
        properties:
          account_type:
            type: string
            enum:
            - unknown
            - iban
            description: Type of the bank account.
          currency:
            description: Currency associated with the bank account.
            type: string
            enum:
            - usd
          swift:
            $ref: '#/components/schemas/UnknownBankAccount'
    CreateExternalAccountUsInput:
      title: ACH/Wire
      description: US bank account using account and routing numbers for ACH or Wire transfers
      allOf:
      - $ref: '#/components/schemas/ExternalAccountBaseWithoutOwnerInfo'
      - type: object
        required:
        - account_type
        - account
        - currency
        - account_owner_name
        - address
        properties:
          account_type:
            type: string
            enum:
            - us
            description: Type of the bank account.
          currency:
            description: Currency associated with the bank account. Must be `usd` for US accounts.
            type: string
            enum:
            - usd
          account:
            $ref: '#/components/schemas/UsBankAccount'
          account_number:
            writeOnly: true
            description: Account number of your bank account. This field is getting deprecated in favor of the `account.account_number` field for US accounts.
            type: string
            minLength: 12
            deprecated: true
          routing_number:
            writeOnly: true
            description: Routing number of your bank account. This field is getting deprecated in favor of the `account.routing_number` field for US accounts.
            type: string
            minLength: 9
            deprecated: true
    ClabeBankAccount:
      required:
      - account_number
      - last_4
      properties:
        account_number:
          type: string
          description: The CLABE account number of the bank account
          minLength: 18
          maxLength: 18
          writeOnly: true
        last_4:
          description: Last 4 digits of the CLABE
          minLength: 4
          maxLength: 4
          type: string
          readOnly: true
    BankAccountOwnerType:
      type: string
      enum:
      - individual
      - business
    CoBankTransferBankAccount:
      title: co_bank_transfer
      description: Colombian CO bank transfer account for COP transfers
      required:
      - account_number
      - bank_code
      - account_type
      - document_type
      - document_number
      - phone_number
      properties:
        account_number:
          type: string
          description: The CO bank account number
          writeOnly: true
        bank_code:
          $ref: '#/components/schemas/ColombianBankCode'
        account_type:
          type: string
          description: The type of bank account
          enum:
          - checking
          - savings
          - electronic_deposit
        document_type:
          $ref: '#/components/schemas/CoBankTransferDocumentType'
        document_number:
          type: string
          description: The document number of the account holder
        phone_number:
          type: string
          description: Phone number of the account holder in E.164 format (e.g. +573001234567)
        last_4:
          description: Last 4 digits of the account number
          minLength: 4
          maxLength: 4
          type: string
          readOnly: true
        routing_number:
          description: The bank code of the account
          type: string
          readOnly: true
    ExternalAccount:
      oneOf:
      - $ref: '#/components/schemas/ExternalAccountUs'
      - $ref: '#/components/schemas/ExternalAccountIban'
      - $ref: '#/components/schemas/ExternalAccountUnknown'
      - $ref: '#/components/schemas/ExternalAccountClabe'
      - $ref: '#/components/schemas/ExternalAccountPix'
      - $ref: '#/components/schemas/ExternalAccountGb'
      - $ref: '#/components/schemas/ExternalAccountBreB'
      - $ref: '#/components/schemas/ExternalAccountCoBankTransfer'
    CreateExternalAccountFPSInput:
      title: FPS
      description: UK bank account information for the Faster Payments payment rail
      allOf:
      - $ref: '#/components/schemas/ExternalAccountBaseWithOwnerInfo'
      - type: object
        required:
        - account_type
        - currency
        - account
        - account_owner_name
        properties:
          account_type:
            type: string
            enum:
            - gb
            description: Type of the bank account.
          currency:
            description: Currency associated with the bank account. Must be `gbp` for GB accounts.
            type: string
            enum:
            - gbp
          account:
            $ref: '#/components/schemas/GbBankAccount'
    ExternalAccountDeactivationReason:
      description: Reason for deactivating an External Account
      type: string
      enum:
      - plaid_item_error
      - deactivated_due_to_bounceback
      - deleted_by_developer
      - requested_by_developer
      - invalid_account_number
      - invalid_bank_validation
      - rejected_by_bank_provider
    ExternalAccountAddress:
      required:
      - street_line_1
      - country
      - city
      properties:
        street_line_1:
          type: string
          minLength: 4
          maxLength: 35
        street_line_2:
          type: string
          maxLength: 35
        city:
          type: string
          minLength: 1
        state:
          type: string
          description: ISO 3166-2 subdivision code. Must be supplied for US addresses.
          minLength: 1
        postal_code:
          type: string
          description: Must be supplied for countries that use postal codes.
          minLength: 1
        country:
          description: Three-letter alpha-3 country code as defined in the ISO 3166-1 spec.
          type: string
          minLength: 3
          maxLength: 3
    ExternalAccountClabe:
      title: CLABE
      description: Mexican CLABE account for SPEI transfers
      allOf:
      - $ref: '#/components/schemas/ExternalAccountBaseWithOwnerInfo'
      - type: object
        required:
        - account_type
        - currency
        - clabe
        - account_owner_name
        properties:
          account_type:
            type: string
            enum:
            - clabe
            description: Type of the bank account.
          currency:
            description: Currency associated with the bank account. Must be `mxn` for CLABE (SPEI) accounts.
            type: string
            enum:
            - mxn
          clabe:
            $ref: '#/components/schemas/ClabeBankAccount'
          account_validation:
            readOnly: true
            nullable: true
            description: Present for CLABE accounts with a successful validation; contains validated owner and bank name.
            $ref: '#/components/schemas/AccountValidation'
    SwiftPurposeOfFunds:
      type: string
      description: The purpose of funds for the Swift account. Can be `intra_group_transfer`, `invoice_for_goods_and_services`
    ExternalAccountResponse:
      required:
      - id
      - customer_id
      - created_at
      - updated_at
      - account_owner_name
      - currency
      - account_type
      - active
      allOf:
      - $ref: '#/components/schemas/ExternalAccount'
      - type: object
        properties:
          account_verification:
            description: Present for accounts with a holder verification check; contains the verification result keyed by account type.
            nullable: true
            type: object
            properties:
              iban:
                type: object
                properties:
                  match_level:
                    type: string
                    enum:
                    - pending
                    - match
                    - close_match
                    - no_match
                    - error
                  reason_code:
                    type: string
                    nullable: true
                  validated_account_owner_name:
                    type: string
                    nullable: true
              gb:
                type: object
                properties:
                  match_level:
                    type: string
                    enum:
                    - pending
                    - match
                    - close_match
                    - no_match
                    - error
                  reason_code:
                    type: string
                    nullable: true
                  validated_account_owner_name:
                    type: string
                    nullable: true
              requested_at:
                type: string
                format: date-time
              completed_at:
                type: string
                format: date-time
                nullable: true
    ExternalAccountGb:
      title: GB
      description: UK bank account using account number and sort code for Faster Payments payment rail
      allOf:
      - $ref: '#/components/schemas/ExternalAccountBaseWithOwnerInfo'
      - type: object
        required:
        - account_type
        - currency
        - account
        - account_owner_name
        properties:
          account_type:
            type: string
            enum:
            - gb
            description: Type of the bank account.
          currency:
            description: Currency associated with the bank account. Must be `gbp` for GB accounts.
            type: string
            enum:
            - gbp
          account:
            $ref: '#/components/schemas/GbBankAccount'
    CreateExternalAccountBreBInput:
      title: Bre-B
      description: 'Colombian Bre-B account for COP transfers. Requires `cop` endorsement. Virtual account numbers are not accepted as Bre-B keys.

        '
      allOf:
      - $ref: '#/components/schemas/ExternalAccountBaseWithoutOwnerInfo'
      - type: object
        required:
        - account_type
        - currency
        - account
        - account_owner_name
        properties:
          currency:
            description: Currency associated with the bank account. Must be `cop` for Bre-B accounts.
            type: string
            enum:
            - cop
          account_type:
            type: string
            enum:
            - bre_b
            description: Type of the bank account.
          account:
            writeOnly: true
            description: Colombian Bre-B bank account information. Required when account type is `bre_b`.
            $ref: '#/components/schemas/BreBBankAccount'
    CoBankTransferDocumentType:
      description: 'Colombian document type identifier. `cc` = Cédula de Ciudadanía, `ce` = Cédula de Extranjería, `nit` = NIT (tax ID), `rut` = RUT (worker registration), `pa` = Passport, `ppt` = Permiso de Protección Temporal.

        '
      type: string
      enum:
      - cc
      - ce
      - nit
      - rut
      - pa
      - ppt
      - ti
      - rc
      - te
      - die
      - nd
    ExternalAccountBaseWithoutOwnerInfo:
      description: Shared writable properties for creating an external account (without account owner info bundle)
      properties:
        id:
          $ref: '#/components/schemas/Id'
          readOnly: true
        customer_id:
          description: The id of the Bridge customer that this External Account belongs to
          type: string
          minLength: 1
          readOnly: true
        bank_name:
          description: Bank name of the account
          type: string
          minLength: 1
          maxLength: 256
        account_owner_name:
          description: Owner of the bank account
          type: string
          minLength: 1
          maxLength: 256
        created_at:
          readOnly: true
          type: string
          description: Time of creation of the External Account
          format: date-time
        updated_at:
          readOnly: true
          type: string
          description: Time of last update of the External Account
          format: date-time
        active:
          readOnly: true
          type: boolean
          description: Whether or not this External Account is active
        address:
          writeOnly: true
          description: Address of the beneficiary of this account.
          $ref: '#/components/schemas/ExternalAccountAddress'
        deactivation_reason:
          readOnly: true
          description: Reason for deactivation when this External Account is inactive
          $ref: '#/components/schemas/ExternalAccountDeactivationReason'
        deactivation_details:
          readOnly: true
          type: string
          description: Additional details about the deactivation when this External Account is inactive
    CreateExternalAccountIbanInput:
      title: IBAN
      description: IBAN bank account for European and international transfers (SEPA transfers use IBAN)
      allOf:
      - $ref: '#/components/schemas/ExternalAccountBaseWithOwnerInfo'
      - type: object
        required:
        - account_type
        - currency
        - iban
        - account_owner_name
        properties:
          account_type:
            type: string
            enum:
            - iban
            description: Type of the bank account.
          currency:
            description: Currency associated with the bank account. Must be `eur` for IBAN accounts.
            type: string
            enum:
            - eur
          iban:
            $ref: '#/components/schemas/IbanBankAccount'
    SwiftBankAccount:
      required:
      - account
      - address
      - category
      - purpose_of_funds
      - short_business_description
      properties:
        account:
          oneOf:
          - $ref: '#/components/schemas/IbanBankAccount'
          - $ref: '#/components/schemas/UnknownBankAccount'
        address:
          description: The bank address
          $ref: '#/components/schemas/Address'
        category:
          description: The context of business operations. Can be `client`, `parent_company`, `subsidiary`, or `supplier`
          $ref: '#/components/schemas/SwiftCategory'
        purpose_of_funds:
          description: The nature of the transactions this account will participate in. Can be `intra_group_transfer`, `invoice_for_goods_and_services`
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/SwiftPurposeOfFunds'
        short_business_description:
          description: How the business uses the funds
          type: string
    ExternalAccountPix:
      title: Pix
      description: Brazilian Pix instant payment system
      allOf:
      - $ref: '#/components/schemas/ExternalAccountBaseWithOwnerInfo'
      - type: object
        required:
        - account_type
        - currency
        properties:
          currency:
            description: Currency associated with the bank account. Must be `brl` for Pix accounts.
            type: string
            enum:
            - brl
          account_type:
            type: string
            enum:
            - pix
            description: Type of the bank account.
          pix_key:
            readOnly: true
            description: Pix key display info. Returned in GET responses when the account uses a Pix key.
            $ref: '#/components/schemas/PixKeyBankAccount'
          br_code:
            readOnly: true
            description: BR Code display info. Returned in GET responses when the account uses a BR Code.
            $ref: '#/components/schemas/BrCodeBankAccount'
          account_validation:
            

# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bridge/refs/heads/main/openapi/bridge-external-accounts-api-openapi.yml