# Search bank account

Search for a bank account using various account schemes.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Banking - Bank accounts",
    "version": "1.0.0",
    "description": "API for managing bank accounts in global formats",
    "contact": {
      "name": "API Support",
      "url": "https://developers.pismo.io/support/"
    },
    "license": {
      "name": "Copyright Pismo"
    }
  },
  "servers": [
    {
      "url": "https://sandbox.pismolabs.io/intl-bankaccounts",
      "description": "Sandbox API server for testing"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Bank accounts",
      "description": "Bank account management endpoints"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Account token - token encoded with Pismo account ID. Tokens can expire quickly, which can result in an **401 Unauthorized** error.",
        "bearerFormat": "JWT"
      }
    },
    "parameters": {
      "schemeNamePath": {
        "name": "schemeNamePath",
        "in": "path",
        "description": "Bank account's scheme (account type): \n`IBAN` - International Bank Account Number  \n`UK-SCAN` - UK bank account - sort code + account number (SCAN)\n`BRAZIL` - Brazilian bank account \n`BBAN` - Basic Bank Account Number\n`ACH` - Automated Clearing House for US Account\n`FEDWIRE` - US Account scheme\n`CLABE` - Mexico bank account scheme\n",
        "required": true,
        "schema": {
          "type": "string",
          "enum": [
            "IBAN",
            "UK-SCAN",
            "BRAZIL",
            "BBAN",
            "ACH",
            "FEDWIRE",
            "CLABE"
          ]
        },
        "example": "IBAN"
      }
    },
    "schemas": {
      "accountID": {
        "type": "integer",
        "description": "Account ID",
        "example": 78123456
      },
      "usaAccountNumber": {
        "type": "string",
        "minLength": 17,
        "maxLength": 17,
        "example": "12345678901234567",
        "description": "Account number"
      },
      "usaRoutingNumber": {
        "type": "string",
        "minLength": 9,
        "maxLength": 9,
        "example": "123456789",
        "description": "A routing number is a nine-digit number used to identify a financial institution in the United States. It is also known as an ABA (American Bankers Association) number.\n"
      },
      "brazilAccountType": {
        "type": "string",
        "enum": [
          "CACC",
          "SLRY",
          "SVGS",
          "TRAN"
        ],
        "maxLength": 4,
        "description": "Account type:  \n  `CACC` - Checking/current account. Known as \"conta corrente\" in Portuguese, this is a bank account type designed for everyday financial transactions and is the most common type individuals and businesses use for day-to-day banking.\n  `SVGS` - Savings account\n  `TRAN` - Payment account. Payment institutions offer payment accounts to move funds and make payments, while banks offer checking accounts that include full financial services such as credit and investments.\n  `SLRY` - Salary account. Employer deposits a fixed amount every month.\n",
        "example": "TRAN"
      },
      "brazilBank": {
        "type": "string",
        "minLength": 8,
        "maxLength": 8,
        "description": "<a href=\"https://bank.codes/numero-do-banco/bank/banco-central-do-brasil/\" target=\"_blank\">ISPB (Identificador do Sistema de Pagamento Brazil)</a> - the Brazilian payment system bank ID, the value is eight digits long.",
        "example": "76523428"
      },
      "brazilBranch": {
        "type": "string",
        "description": "Branch code, a 4-digit value. Values under four digits are left-padded with zeroes.",
        "minLength": 1,
        "maxLength": 4,
        "example": "0186"
      },
      "brazilAccountNumber": {
        "type": "string",
        "minLength": 1,
        "maxLength": 13,
        "example": "1773065291",
        "description": "Account number. Cannot contain leading zeroes."
      },
      "creationDatetime": {
        "type": "string",
        "format": "date-time",
        "description": "Account creation date time displayed in ISO 8601 format `2023-04-12T23:20:50.52Z`.",
        "example": "2023-04-12T23:20:50.52Z"
      },
      "domain.Error": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error type code",
            "example": "EIBA0001"
          },
          "details": {
            "type": "string",
            "description": "Error details",
            "example": "Key not found"
          },
          "message": {
            "type": "string",
            "description": "Error message",
            "example": "Key not found"
          }
        }
      },
      "intlbankaccounts.BrazilScheme": {
        "type": "object",
        "required": [
          "bank",
          "branch",
          "account_number",
          "supplementary_data"
        ],
        "properties": {
          "bank": {
            "$ref": "#/components/schemas/brazilBank"
          },
          "branch": {
            "$ref": "#/components/schemas/brazilBranch"
          },
          "account_number": {
            "$ref": "#/components/schemas/brazilAccountNumber"
          },
          "supplementary_data": {
            "$ref": "#/components/schemas/intlbankaccounts.BrazilSupplementaryData"
          }
        }
      },
      "intlbankaccounts.BbanScheme": {
        "type": "object",
        "required": [
          "bban"
        ],
        "properties": {
          "bban": {
            "type": "string",
            "description": "Basic Bank Account Number (BBAN). BBAN is a bank account numbering system used in many countries, especially in Europe.",
            "maxLength": 30,
            "example": "GB539007547034"
          }
        }
      },
      "intlbankaccounts.BrazilSupplementaryData": {
        "type": "object",
        "required": [
          "account_type"
        ],
        "properties": {
          "account_type": {
            "$ref": "#/components/schemas/brazilAccountType"
          }
        }
      },
      "intlbankaccounts.IbanScheme": {
        "type": "object",
        "required": [
          "iban"
        ],
        "properties": {
          "iban": {
            "type": "string",
            "maxLength": 34,
            "description": "International Bank Account Number (IBAN).\n\nIBAN structure varies by country, but typically includes a 2 letter country code, two check digits for error detection, a bank identifier and an account number.\n",
            "example": "GB29NWBK60161331926819"
          }
        }
      },
      "intlbankaccounts.AchScheme": {
        "type": "object",
        "required": [
          "account_number",
          "routing_number"
        ],
        "properties": {
          "account_number": {
            "$ref": "#/components/schemas/usaAccountNumber"
          },
          "routing_number": {
            "$ref": "#/components/schemas/usaRoutingNumber"
          }
        }
      },
      "intlbankaccounts.FedWireScheme": {
        "type": "object",
        "required": [
          "account_number",
          "routing_number"
        ],
        "properties": {
          "account_number": {
            "$ref": "#/components/schemas/usaAccountNumber"
          },
          "routing_number": {
            "$ref": "#/components/schemas/usaRoutingNumber"
          }
        }
      },
      "intlbankaccounts.ClabeScheme": {
        "type": "object",
        "required": [
          "clabe"
        ],
        "properties": {
          "clabe": {
            "type": "string",
            "length": 18,
            "description": "The Clave Bancaria Estandarizada (CLABE) is an 18-digit standardized bank code used for identifying bank accounts in Mexico.\n",
            "example": "003290103581700922"
          }
        }
      },
      "intlbankaccounts.IntlBankAccountExternal": {
        "type": "object",
        "properties": {
          "account_id": {
            "$ref": "#/components/schemas/accountID"
          },
          "creation_datetime": {
            "$ref": "#/components/schemas/creationDatetime"
          },
          "updated_datetime": {
            "$ref": "#/components/schemas/updatedDatetime"
          },
          "metadata": {
            "$ref": "#/components/schemas/metadata"
          },
          "scheme": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/intlbankaccounts.IbanScheme"
              },
              {
                "$ref": "#/components/schemas/intlbankaccounts.UkScanScheme"
              },
              {
                "$ref": "#/components/schemas/intlbankaccounts.BrazilScheme"
              },
              {
                "$ref": "#/components/schemas/intlbankaccounts.BbanScheme"
              },
              {
                "$ref": "#/components/schemas/intlbankaccounts.AchScheme"
              },
              {
                "$ref": "#/components/schemas/intlbankaccounts.FedWireScheme"
              },
              {
                "$ref": "#/components/schemas/intlbankaccounts.ClabeScheme"
              }
            ]
          }
        }
      },
      "intlbankaccounts.IntlBankAccountSearchRequest": {
        "type": "object",
        "required": [
          "scheme"
        ],
        "properties": {
          "scheme": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/intlbankaccounts.IbanScheme"
              },
              {
                "$ref": "#/components/schemas/intlbankaccounts.UkScanScheme"
              },
              {
                "$ref": "#/components/schemas/intlbankaccounts.BrazilScheme"
              },
              {
                "$ref": "#/components/schemas/intlbankaccounts.BbanScheme"
              },
              {
                "$ref": "#/components/schemas/intlbankaccounts.AchScheme"
              },
              {
                "$ref": "#/components/schemas/intlbankaccounts.FedWireScheme"
              },
              {
                "$ref": "#/components/schemas/intlbankaccounts.ClabeScheme"
              }
            ]
          }
        }
      },
      "intlbankaccounts.UkScanScheme": {
        "required": [
          "account_number",
          "sort_code"
        ],
        "type": "object",
        "properties": {
          "account_number": {
            "type": "string",
            "maxLength": 8,
            "description": "Account number"
          },
          "sort_code": {
            "$ref": "#/components/schemas/sortCode"
          }
        }
      },
      "metadata": {
        "additionalProperties": true,
        "type": "object",
        "description": "A set of key-value pairs used to store custom data or additional information."
      },
      "sortCode": {
        "type": "string",
        "description": "In UK banking, a sort code is a unique identifier used to route money transfers between banks and financial institutions. Similar to a routing number in the US. It is a six-digit number that identifies both the bank and the specific branch office. Each bank branch office has its own unique sort code. The first two digits identity the bank and the remaining 4 digits identify the branch.\n",
        "maxLength": 6,
        "minLength": 6,
        "example": "123456"
      },
      "updatedDatetime": {
        "type": "string",
        "format": "date-time",
        "description": "Updated date time. A RFC 3339 value, i.e., \"2023-04-12T23:20:50.52Z\".",
        "example": "2023-04-12T23:20:50.52Z"
      }
    }
  },
  "paths": {
    "/v3/bank-accounts/{schemeNamePath}/search": {
      "post": {
        "tags": [
          "Bank accounts"
        ],
        "summary": "Search bank account",
        "description": "Search for a bank account using various account schemes.",
        "operationId": "post-intl-bank-accounts-v3-bank-accounts-scheme-name-search",
        "parameters": [
          {
            "$ref": "#/components/parameters/schemeNamePath"
          }
        ],
        "requestBody": {
          "description": "Request body matching the scheme specified in the path parameter.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/intlbankaccounts.IntlBankAccountSearchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "x-cid": {
                "description": "Request tracking identifier.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/intlbankaccounts.IntlBankAccountExternal"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "headers": {
              "x-cid": {
                "description": "Request tracking identifier.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/domain.Error"
                },
                "examples": {
                  "EIBA0009": {
                    "summary": "Validation Error",
                    "value": {
                      "code": "EIBA0009",
                      "message": "Validation error"
                    }
                  },
                  "EIBA0012": {
                    "summary": "Accounts API invalid request",
                    "value": {
                      "code": "EIBA0012",
                      "message": "Accounts - API returned 4xx error"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "headers": {
              "x-cid": {
                "description": "Request tracking identifier.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/domain.Error"
                },
                "examples": {
                  "EIBA0006": {
                    "summary": "Missing tenant header",
                    "value": {
                      "code": "EIBA0006",
                      "message": "Missing required header: 'x-tenant'"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "headers": {
              "x-cid": {
                "description": "Request tracking identifier.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/domain.Error"
                },
                "examples": {
                  "EIBA0029": {
                    "summary": "Intl Bank Account not found",
                    "value": {
                      "code": "EIBA0029",
                      "message": "IntlBankAccount not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server",
            "headers": {
              "x-cid": {
                "description": "Request tracking identifier.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/domain.Error"
                },
                "examples": {
                  "EIBA0005": {
                    "summary": "HTTP error",
                    "value": {
                      "code": "EIBA0005",
                      "message": "HTTP error"
                    }
                  },
                  "EIBA0011": {
                    "summary": "Accounts API server error",
                    "value": {
                      "code": "EIBA0011",
                      "message": "Accounts - API returned 5xx error"
                    }
                  },
                  "EIBA0013": {
                    "summary": "Accounts API timeout",
                    "value": {
                      "code": "EIBA0013",
                      "message": "Accounts - API timeout"
                    }
                  },
                  "EIBA0015": {
                    "summary": "Database error",
                    "value": {
                      "code": "EIBA0015",
                      "message": "Database internal error"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```