> ## Documentation Index > Fetch the complete documentation index at: https://docs.bolta.io/llms.txt > Use this file to discover all available pages before exploring further. # Bank Account Holder > Look up account holder names with a bank code and an account number: requirements, pricing, bulk inquiry, and amount-verified virtual accounts. ## What you can look up Send a bank code and an account number, and the API returns the account holder name. Use it to confirm a payee account before you transfer money. | Path | Purpose | | ----------------------------------------- | ----------------------------------------- | | `POST /v1/bankAccountHolders:inquire` | Look up the holder of one account | | `POST /v1/bankAccountHolders:bulkInquire` | Look up the holders of up to 100 accounts | ## Requirements Neither path needs issuer registration, a joint certificate, a client reference id (`Bolta-Client-Reference-Id`), or any particular subscription plan. Set `Basic {apiKey}` in the `Authorization` header. See the [authentication guide](/en/api-introduction/authentication) for details. ## Pricing Each account that returns a holder name deducts **50 points**. An account with no holder or a failed lookup, invalid input, an exceeded limit, an insufficient balance, and any test key call deduct nothing. For a regular account, repeating the same bank code and account number in one request deducts only once. An amount-verified virtual account deducts once per distinct `amount`. Sending the request again deducts again. ## Single inquiry ```bash theme={"dark"} curl -X POST https://xapi.bolta.io/v1/bankAccountHolders:inquire \ -H "Authorization: Basic {apiKey}" \ -H "Content-Type: application/json" \ -d '{ "bankCode": "088", "accountNumber": "100-0000-001" }' ``` | Field | Type | Required | Description | | --------------- | ------- | -------- | -------------------------------------------------------------------------------------------------- | | `bankCode` | string | Yes | Three-digit KFTC bank code. See the supported banks below | | `accountNumber` | string | Yes | Account number. Hyphens are allowed. Without hyphens it must be 6 to 20 digits | | `amount` | integer | No | Deposit amount in KRW for an amount-verified virtual account. Leave it empty for a regular account | The API returns `200 OK` with the response below. ```json theme={"dark"} { "bankCode": "088", "accountNumber": "1000000001", "holderName": "홍길동" } ``` | Field | Type | Description | | --------------- | ------ | ----------------------------------- | | `bankCode` | string | The bank code you sent | | `accountNumber` | string | Account number with hyphens removed | | `holderName` | string | Account holder name | ## Supported banks `bankCode` is the three-digit KFTC standard bank code. Bolta supports these 26 domestic banks. | `bankCode` | Bank | | ---------- | ---------------------- | | `002` | Korea Development Bank | | `003` | IBK | | `004` | KB Kookmin Bank | | `005` | KEB | | `007` | Suhyup | | `011` | NongHyup Bank | | `012` | Local NongHyup | | `020` | Woori Bank | | `023` | SC First Bank | | `027` | Citibank Korea | | `031` | iM Bank (Daegu Bank) | | `032` | Busan Bank | | `034` | Kwangju Bank | | `035` | Jeju Bank | | `037` | Jeonbuk Bank | | `039` | Kyongnam Bank | | `045` | KFCC | | `048` | CU (Credit Union) | | `050` | Savings Bank | | `064` | Forestry Cooperative | | `071` | Korea Post | | `081` | Hana Bank | | `088` | Shinhan Bank | | `089` | K bank | | `090` | KakaoBank | | `092` | Toss Bank | Supported foreign banks are `054` HSBC, `055` Deutsche Bank, `056` RBS, `057` JPMorgan Chase, `058` Mizuho, `059` MUFG, `060` Bank of America, `061` BNP Paribas, `062` ICBC, `063` Bank of China, and `067` China Construction Bank. A code outside these lists returns `400` with `UNSUPPORTED_BANK`. That covers `001` Bank of Korea, `008` Korea Eximbank, `026` Seoul Bank, `052` Morgan Stanley Bank, `065` Daehwa Bank, `066` Bank of Communications, `900` HANMI Bank, `901` Kansai Mirai Bank, and `902` KEB Hana Bank (JP). ## Bulk inquiry Put 1 to 100 accounts in `accounts`. ```bash theme={"dark"} curl -X POST https://xapi.bolta.io/v1/bankAccountHolders:bulkInquire \ -H "Authorization: Basic {apiKey}" \ -H "Content-Type: application/json" \ -d '{ "accounts": [ { "bankCode": "088", "accountNumber": "1000000001" }, { "bankCode": "089", "accountNumber": "1000000004" } ] }' ``` The API returns one result per account, in the order you sent them. ```json theme={"dark"} { "results": [ { "bankCode": "088", "accountNumber": "1000000001", "holderName": "홍길동", "error": null }, { "bankCode": "089", "accountNumber": "1000000004", "holderName": null, "error": { "code": "AMOUNT_REQUIRED", "message": "입금 금액이 정해진 가상계좌입니다. 총 지급 금액을 입력한 뒤 예금주를 다시 조회해 주세요." } } ] } ``` | Field | Type | Description | | ---------------------- | -------------- | ---------------------------------------------------------------------- | | `results` | array | One item per requested account, in the order you sent them | | `results[].holderName` | string or null | Holder name. `null` when none was found | | `results[].error` | object or null | Why no holder was found. `code` matches the single inquiry error codes | The API returns `message` as a Korean sentence. If any item has an invalid format, the API rejects the whole request with `400 INVALID_REQUEST`. An item whose `error.code` is `BANK_UNAVAILABLE` was not verified. Retry that account alone shortly. If the bank verifies no account at all, the API returns `503 BANK_UNAVAILABLE` instead of this response. ## Amount-verified virtual accounts A virtual account with a fixed deposit amount verifies the holder only when you send that amount. Looking it up without `amount` returns `AMOUNT_REQUIRED`. Set `amount` to the total you plan to transfer and look it up again. A different amount returns `AMOUNT_MISMATCH`. ## Daily limit You can look up **10,000 accounts** per day. Bolta counts accounts, not requests. Test keys and live keys have separate counters. At the limit the API returns `429` with `RATE_LIMITED`. Retry after `Retry-After`. One lookup waits up to 45 seconds. Past that it ends as `503 BANK_UNAVAILABLE` and deducts nothing. ## Test keys A test key deducts no points and accepts only the account numbers below. Any supported bank code works. | Account number | Result | | -------------- | ----------------------------------------------------------------------------------------------- | | `1000000001` | `holderName` is `홍길동` | | `1000000002` | `holderName` is `(주)볼타` | | `1000000003` | `ACCOUNT_NOT_VERIFIED` | | `1000000004` | `AMOUNT_REQUIRED` without `amount`, `김볼타` with `20000`, `AMOUNT_MISMATCH` with any other amount | | `1000000005` | `BANK_UNAVAILABLE` | Any other account number returns `400 INVALID_REQUEST`. ## Errors When a holder lookup fails, a single inquiry returns HTTP 400, while a bulk inquiry returns the item error in `results[].error` with HTTP 200. | Status code | Error code | Condition | | ----------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `400` | `INVALID_REQUEST` | Invalid request format, more than 100 accounts, or a test key requesting an account outside the fixed list | | `400` | `ACCOUNT_NOT_VERIFIED` | The account could not be verified. Check the bank code and account number | | `400` | `ACCOUNT_NOT_AVAILABLE` | The virtual account cannot accept deposits. Contact the issuing institution | | `400` | `AMOUNT_REQUIRED` | The virtual account has a fixed deposit amount. Set `amount` and look it up again | | `400` | `AMOUNT_MISMATCH` | The `amount` you sent differs from the amount fixed on the virtual account | | `400` | `AMOUNT_VERIFICATION_UNAVAILABLE` | Bolta cannot look up this amount-verified virtual account right now. Confirm the holder with the issuing institution | | `400` | `UNSUPPORTED_BANK` | The bank code does not support account holder lookup | | `401` | - | API key authentication failed. No response body | | `402` | `PAYMENT_REQUIRED` | Insufficient point balance. Top up in the developer center | | `403` | `FORBIDDEN` | No access to the requested resource | | `409` | `POINT_RESERVED_BY_IN_FLIGHT_REQUESTS` | Insufficient balance once in-flight requests are counted. Top up or retry after they finish | | `429` | `RATE_LIMITED` | Daily lookup limit exceeded. Retry after `Retry-After` | | `500` | `INTERNAL_SERVER_ERROR` | Internal server error | | `503` | `BANK_UNAVAILABLE` | Bank maintenance or a connection error | | `503` | `LOOKUP_UNAVAILABLE` | Bolta cannot evaluate the lookup protection limit | | `503` | `SERVICE_UNAVAILABLE` | Temporary internal API communication error | See [Error codes](/en/api-introduction/error-codes) for the full list. ## Related documents * [Inquire Bank Account Holder API](/api-reference/bank-account-holder/inquire-bank-account-holder) * [Bulk Inquire Bank Account Holders API](/api-reference/bank-account-holder/bulk-inquire-bank-account-holders) * [Pricing](/en/api-introduction/pricing) * [Bank account transactions](/en/api-introduction/bank-account-transactions)