Bank Account Holder

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 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

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.

{
  "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.

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.

{
  "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 for the full list.

API Introduction

API Guides

Use Cases

SDK / No-code

What you can look up

Requirements

Pricing

Single inquiry

Supported banks

Bulk inquiry

Amount-verified virtual accounts

Daily limit

Test keys

Errors

​What you can look up

​Requirements

​Pricing

​Single inquiry

​Supported banks

​Bulk inquiry

​Amount-verified virtual accounts

​Daily limit

​Test keys

​Errors

​Related documents

What you can look up

Requirements

Pricing

Single inquiry

Supported banks

Bulk inquiry

Amount-verified virtual accounts

Daily limit

Test keys

Errors

Related documents