Business Registration Certificate Extraction and Verification

What it does

Send one business registration certificate file, and the API returns the business registration number, business name, representative names, opening date, address, and industries. It also verifies the business registration number, representative name, and opening date it read against National Tax Service (NTS) records. Use it to save customers or members from typing their business details.

Path	Purpose
`POST /v1/businessRegistrationCertificates:extract`	Extract and verify one business registration certificate

Requirements

This API needs no issuer registration, no certificate, and no client reference id (Bolta-Client-Reference-Id), on any subscription plan. Set Basic {apiKey} in the Authorization header. See the authentication guide.

Pricing

Each document whose NTS verification result (validation) is MATCHED or NOT_MATCHED deducts 100 points. An UNAVAILABLE result, an error response, and any test key call deduct nothing. Sending the same file again deducts again.

Request

Put one file in the file part of a multipart/form-data body.

curl -X POST https://xapi.bolta.io/v1/businessRegistrationCertificates:extract \
  -H "Authorization: Basic {apiKey}" \
  -F "file=@certificate.pdf"

Part	Type	Required	Description
`file`	file	Yes	One business registration certificate file

Supported formats are PDF, JPG, PNG, and WebP.
The file must be 5 MB (5,242,880 bytes) or smaller. A PDF must have 5 pages or fewer.
Send one document per request. Send several documents one at a time.
The API accepts business registration certificates only. Other documents, such as a business registration proof or a corporate registry, and files whose business registration number cannot be read return 400 INVALID_FILE.

The API reads PDFs downloaded from Hometax most accurately. When users upload a photo, ask them to capture the whole document with sharp text. If the API returns 400 INVALID_FILE because it cannot read the business registration number, ask the user to take the photo again.

Response

The API returns 200 OK with the response below.

{
  "certificate": {
    "businessRegistrationNumber": "1000000014",
    "organizationName": "(주)볼타테스트",
    "representativeNames": ["김볼타"],
    "openedOn": "2020-01-01",
    "address": "서울특별시 테스트구 가상로 1",
    "industries": [
      { "businessType": "정보통신업", "businessItem": "응용 소프트웨어 개발 및 공급업" }
    ],
    "corporationRegistrationNumber": "1101110000000",
    "taxRegistrationId": null
  },
  "inputQuality": "SUFFICIENT",
  "validation": "MATCHED"
}

Field	Type	Description
`certificate`	object	Values read from the document
`certificate.businessRegistrationNumber`	string	Ten-digit business registration number without hyphens
`certificate.organizationName`	string or null	Business name (corporate name)
`certificate.representativeNames`	array of string	Representative names in printed order, up to 10
`certificate.openedOn`	string or null	Opening date in `YYYY-MM-DD` format
`certificate.address`	string or null	Business address
`certificate.industries`	array	Industry rows in printed order, up to 20
`certificate.industries[].businessType`	string or null	Business type
`certificate.industries[].businessItem`	string or null	Business item
`certificate.corporationRegistrationNumber`	string or null	Thirteen-digit corporation registration number without hyphens. Corporate certificates only
`certificate.taxRegistrationId`	string or null	Four-digit sub-business place number
`inputQuality`	string	Image resolution check
`validation`	string	NTS verification result

The response always contains every field. A value the API could not read is null, and a list is empty. If the API cannot read the business registration number, it returns 400 INVALID_FILE instead of a result. representativeNames holds every co-representative and drops role labels such as (공동대표). For a joint sole proprietorship, the certificate prints one representative in the name field, and the list holds only that person. Where you accept a single representative, use the first item. In industries, the business type and business item in the same row form a pair. If you need a primary industry, use the first row.

`validation`

Value	Meaning	Deduction
`MATCHED`	The business registration number, first representative name, and opening date match NTS records	100 points
`NOT_MATCHED`	The API could not confirm a match with NTS records	100 points
`UNAVAILABLE`	An NTS outage prevented verification. The response still contains the values read	None

NTS verification uses three values: the business registration number, the first representative name, and the opening date. Ask users to confirm the business name, address, and industries themselves.

`inputQuality`

Value	Meaning
`SUFFICIENT`	Resolution is sufficient
`LOW_RESOLUTION`	Low resolution may have garbled the address or industries. Ask for a larger image or a PDF

Prefilling input forms

When validation is MATCHED and inputQuality is SUFFICIENT, you can prefill an input form with the values. Let users review and correct the values before you save them or issue a tax invoice.

Processing time

The API finishes each request within about 45 seconds. Set your client read timeout to 60 seconds or more. If extraction does not finish in time, the API returns 503 EXTRACTION_UNAVAILABLE.

Data retention

Bolta does not store uploaded files or the values read from them. The response never contains personal identification numbers such as resident registration numbers.

Test key

A test key returns the fixed result shown in the response example above, regardless of the uploaded file, and deducts no points. An empty file, a file over 5 MB, or an unsupported format returns the same error as with a live key. The fixed 1000000014 is the active-business number for the business registration status test key, so you can pass the extracted number straight to a status check with a test key.

Rate limits

Limit	Value	When exceeded
Concurrent requests	1 per partner, live keys only	`429 TOO_MANY_IN_FLIGHT`
Daily volume	1,000 per 24 hours, counted separately for test and live keys	`429 RATE_LIMITED`
Bolta extraction capacity	Shared across Bolta	`429 RATE_LIMITED`

With a live key, wait for the previous response before you send the next file. All live keys of the same partner share the concurrency limit. When you receive 429, wait the number of seconds in the Retry-After header and send the same file again.

Errors

Status code	Error code	Condition
`400`	`INVALID_REQUEST`	Missing `file` part, empty file, or a file over 5 MB
`400`	`INVALID_FILE`	Unsupported format, unreadable file, PDF over 5 pages, or a document that is not a business registration certificate or whose business registration number cannot be read
`401`	-	API key authentication failed. No response body
`402`	`PAYMENT_REQUIRED`	Insufficient point balance. Top up in the developer center
`409`	`POINT_RESERVED_BY_IN_FLIGHT_REQUESTS`	Insufficient balance once in-flight requests are counted. Top up or retry after they finish
`415`	`UNSUPPORTED_MEDIA_TYPE`	`Content-Type` is not `multipart/form-data`
`429`	`TOO_MANY_IN_FLIGHT`	The same partner already has a request in progress. Retry after `Retry-After`
`429`	`RATE_LIMITED`	Daily volume exceeded or Bolta extraction capacity full. Retry after `Retry-After`
`500`	`INTERNAL_SERVER_ERROR`	Internal server error
`503`	`EXTRACTION_UNAVAILABLE`	Extraction failed or timed out. Retry later
`503`	`LOOKUP_UNAVAILABLE`	Bolta cannot evaluate the rate limit
`503`	`SERVICE_UNAVAILABLE`	Temporary internal API communication error

The message of INVALID_FILE differs by cause, and you can show it to users as is. The messages are in Korean.

Cause	`message`
Format	jpg, png, webp, pdf 형식만 업로드할 수 있습니다.
Unreadable file	파일을 읽을 수 없습니다. 사업자등록증 파일을 확인해 주세요.
Page count	5쪽 이하의 PDF만 업로드할 수 있습니다.
Not a business registration certificate, or business registration number unreadable	사업자등록증을 찾지 못했습니다. 사업자등록증명이나 등기사항증명서 같은 다른 서류는 받지 않습니다. 사업자등록증 파일을 확인해 주세요.

See Error codes for the full list.

API Introduction

API Guides

Use Cases

SDK / No-code

Business Registration Certificate Extraction and Verification

What it does

Requirements

Pricing

Request

Response

`validation`

`inputQuality`

Prefilling input forms

Processing time

Data retention

Test key

Rate limits

Errors

​What it does

​Requirements

​Pricing

​Request

​Response

​validation

​inputQuality

​Prefilling input forms

​Processing time

​Data retention

​Test key

​Rate limits

​Errors

​Related documents

What it does

Requirements

Pricing

Request

Response

`validation`

`inputQuality`

Prefilling input forms

Processing time

Data retention

Test key

Rate limits

Errors

Related documents