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

# Business Profile

> Search for businesses by name or business registration number and retrieve a detailed profile: request, response, pricing, and rate limits.

## What it looks up

Search and retrieve business profiles that Bolta compiles from public data. Use it to let users search for and pick a business on a customer registration screen, or to fill in the business name, address, and industry of a customer when you only have its business registration number.

| Path | Purpose |
| - | - |
| `GET /v1/businessProfiles:search` | Search for businesses by business name, representative name, or business registration number |
| `GET /v1/businessProfiles/{businessRegistrationNumber}` | Retrieve the detailed profile of one business registration number |

Search first, then retrieve the profile of the business you picked. A search result holds only the values needed to tell businesses apart. The full representative name, address, contact details, and industry are in the profile response.

## 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](/en/docs/api-introduction/authentication).

## Pricing

| Path | Price |
| - | - |
| Search | 9 points for each result returned |
| Profile retrieval | 90 points for each successful retrieval |

* A search with no results, a `404` on profile retrieval, an error response, and any test key call deduct nothing.
* A call that fetches the next results deducts for the results it returns. One call deducts at most `limit` × 9 points.
* Retrieving the same business registration number again deducts again.
* When your balance is lower than the price of the results, the API returns `402` or `409` instead of a partial result. Lower `limit` when your balance is low.
* Before a lookup, the API checks that your balance covers one unit (9 points for search, 90 points for profile retrieval). If it does not, the API returns `402` or `409` regardless of the result.

## Search

### Request

```bash theme={"dark"}
curl -G https://xapi.bolta.io/v1/businessProfiles:search \
  -H "Authorization: Basic {apiKey}" \
  --data-urlencode "keyword=테스트상사" \
  -d "limit=3"
```

| Parameter | Required | Description |
| - | - | - |
| `keyword` | O | Search keyword |
| `limit` | X | Number of results per call. 1 to 50, default 20 |
| `cursor` | X | The `nextCursor` of the previous response. Send it back unchanged |
| `excludeStatuses` | X | Registration states to exclude from the results. `SUSPENDED` and `CLOSED`, separated by commas |

`keyword` matches the values below.

* Business name, former business name, and English business name
* Representative name
* Three or more initial consonants of the business name (for example, `ㅌㅅㅌ`)
* A ten-digit business registration number, with or without hyphens. A number search returns that one business

When you separate several words with spaces, the API finds businesses that match every word. Add a region or industry name to narrow the results. For example, `다온 강남` finds businesses named 다온 in Gangnam-gu.

Enter a keyword of 100 characters or fewer after trimming, with at least 2 characters once spaces and symbols are removed. A keyword that holds only a legal form, such as `주식회사`, returns `400 INVALID_REQUEST`.

`excludeStatuses` removes businesses confirmed as suspended or closed. Businesses whose state Bolta has not checked (`registration` is `null`) and businesses in the `NOT_REGISTERED` or `UNKNOWN` state stay in the results. To confirm the state before a transaction, use [Business Registration Status](/en/docs/api-introduction/business-registration-status).

| Input | Result |
| - | - |
| Omitted | No filtering by state |
| `CLOSED` | Excludes closed businesses |
| `SUSPENDED,CLOSED` | Excludes suspended and closed businesses |

An empty value, a duplicated value, or any other value such as `ACTIVE` returns `400 INVALID_REQUEST`.

### Response

```json theme={"dark"}
{
  "items": [
    {
      "businessRegistrationNumber": "1000000014",
      "organizationName": "테스트상사 주식회사",
      "representativeName": "김*타",
      "registration": { "status": "ACTIVE" },
      "region": "서울특별시 강남구"
    },
    {
      "businessRegistrationNumber": "1000000028",
      "organizationName": "테스트상사 간이점",
      "representativeName": "이*스",
      "registration": { "status": "ACTIVE" },
      "region": "서울특별시 마포구"
    },
    {
      "businessRegistrationNumber": "1000000106",
      "organizationName": "테스트상사 세금계산서점",
      "representativeName": "박*의",
      "registration": { "status": "ACTIVE" },
      "region": "부산광역시 해운대구"
    }
  ],
  "nextCursor": "djE6MDotOjM6MzFmN2UxZGI0NjJkMzVhMQ",
  "hasMore": true
}
```

| Field | Type | Description |
| - | - | - |
| `items` | array | Search results, most relevant first |
| `items[].businessRegistrationNumber` | string | Ten-digit business registration number without hyphens |
| `items[].organizationName` | string or null | Business name |
| `items[].representativeName` | string or null | Representative name with the middle masked |
| `items[].registration` | object or null | Business registration state Bolta last checked. `null` if Bolta has never checked it |
| `items[].registration.status` | string | Business registration state |
| `items[].region` | string or null | Province and district name. Province only when the district is unknown |
| `nextCursor` | string or null | Cursor for the next results. `null` on the last page |
| `hasMore` | boolean | `true` when more results exist |

The response always contains every field. A missing value is `null`, and `items` is an empty array when nothing matches.

### Fetching the next results

When `hasMore` is `true`, call again with `nextCursor` in `cursor`. Send the same `keyword` and `excludeStatuses` as the first request. You can change `limit`.

```bash theme={"dark"}
curl -G https://xapi.bolta.io/v1/businessProfiles:search \
  -H "Authorization: Basic {apiKey}" \
  --data-urlencode "keyword=테스트상사" \
  -d "limit=3" \
  -d "cursor=djE6MDotOjM6MzFmN2UxZGI0NjJkMzVhMQ"
```

<Warning>
  `hasMore` can be `true` even when a response holds fewer results than `limit`. Keep calling based on `hasMore`, not on the number of `items`.
</Warning>

* One keyword returns up to the first 1,000 results. If you need more, make the keyword more specific.
* A cursor is bound to the `keyword`, `excludeStatuses`, and key mode (test or live) it was issued for. If any of them differs or the cursor is stale, the API returns `400 INVALID_CURSOR`. Search again from the start without a cursor.

## Profile retrieval

### Request

```bash theme={"dark"}
curl https://xapi.bolta.io/v1/businessProfiles/1000000014 \
  -H "Authorization: Basic {apiKey}"
```

Put a ten-digit business registration number in the path. Hyphens are allowed, as in `100-00-00014`. The API validates the format and the checksum. It returns `400 INVALID_REQUEST` when the number is not ten digits, and `400 INVALID_BUSINESS_REGISTRATION_NUMBER` when the checksum does not match.

A number with no profile in Bolta returns `404 NOT_FOUND`.

### Response

```json theme={"dark"}
{
  "businessRegistrationNumber": "1000000014",
  "corporateRegistrationNumber": "1101110000006",
  "businessKind": "CORPORATE",
  "commercialSalesNumber": "2021-서울강남-01234",
  "organizationName": "테스트상사 주식회사",
  "organizationNameEnglish": "Test Sangsa Co., Ltd.",
  "formerOrganizationNames": [
    { "name": "주식회사 테스트랩스", "changedOn": "2022-03-01" }
  ],
  "representativeName": "김볼타",
  "address": {
    "roadAddress": "서울특별시 강남구 가상로 1",
    "postalCode": "06236",
    "sidoCode": "11",
    "sigunguCode": "11680"
  },
  "contact": {
    "phone": "02-000-0000",
    "email": "hello@example.com",
    "websites": ["https://example.com"]
  },
  "industry": {
    "businessType": "서비스업",
    "businessItem": "응용 소프트웨어 개발",
    "standardIndustry": { "code": "58222", "name": "응용 소프트웨어 개발 및 공급업" },
    "category": { "code": "J", "name": "정보통신업" }
  },
  "openedOn": "2021-03-02",
  "businessRegisteredOn": "2021-03-02",
  "corporationEstablishedOn": "2021-02-25",
  "registration": {
    "status": "ACTIVE",
    "closedOn": null,
    "checkedAt": "2025-12-31T15:00:00Z"
  },
  "taxation": {
    "type": "GENERAL"
  }
}
```

The response always contains every field. A missing value is `null`, and a list is empty.

#### Identification

| Field | Type | Description |
| - | - | - |
| `businessRegistrationNumber` | string | Ten-digit business registration number without hyphens |
| `corporateRegistrationNumber` | string or null | Thirteen-digit corporation registration number without hyphens |
| `businessKind` | string or null | Business kind |
| `commercialSalesNumber` | string or null | Mail-order business report number |

#### Business name and representative

| Field | Type | Description |
| - | - | - |
| `organizationName` | string or null | Business name |
| `organizationNameEnglish` | string or null | English business name |
| `formerOrganizationNames` | array | Former business names, most recently changed first |
| `formerOrganizationNames[].name` | string | Former business name |
| `formerOrganizationNames[].changedOn` | string or null | Date the new business name first appeared in public filings, in `YYYY-MM-DD` format. It can differ from the registration date of the change |
| `representativeName` | string or null | Representative name. A value the source masked stays masked |

#### Address and contact

| Field | Type | Description |
| - | - | - |
| `address` | object or null | Address. `null` when the source has no address |
| `address.roadAddress` | string or null | Road name address |
| `address.postalCode` | string or null | Five-digit postal code |
| `address.sidoCode` | string or null | Two-digit legal district code of the province |
| `address.sigunguCode` | string or null | Five-digit legal district code of the district |
| `contact` | object | Contact details. Always an object |
| `contact.phone` | string or null | Main phone number, formatted with hyphens |
| `contact.email` | string or null | Main email address |
| `contact.websites` | array of string | Website URLs |

#### Industry

| Field | Type | Description |
| - | - | - |
| `industry` | object | Industry. Always an object |
| `industry.businessType` | string or null | Business type as registered with the NTS |
| `industry.businessItem` | string or null | Business item as registered with the NTS |
| `industry.standardIndustry` | object or null | Korean Standard Industrial Classification (11th revision) sub-subclass |
| `industry.standardIndustry.code` | string | Five-digit sub-subclass code |
| `industry.standardIndustry.name` | string | Sub-subclass name |
| `industry.category` | object or null | Korean Standard Industrial Classification section |
| `industry.category.code` | string | Section code, `A` to `U` |
| `industry.category.name` | string | Section name |

#### Dates

| Field | Type | Description |
| - | - | - |
| `openedOn` | string or null | Opening date in `YYYY-MM-DD` format |
| `businessRegisteredOn` | string or null | Business registration date in `YYYY-MM-DD` format |
| `corporationEstablishedOn` | string or null | Corporation establishment date in `YYYY-MM-DD` format |

The three dates come from different sources and can differ.

#### Business registration state

| Field | Type | Description |
| - | - | - |
| `registration` | object or null | Business registration state Bolta last checked. `null` if Bolta has never checked it |
| `registration.status` | string | Business registration state |
| `registration.closedOn` | string or null | Closing date in `YYYY-MM-DD` format |
| `registration.checkedAt` | string | Time Bolta checked with the NTS, in ISO 8601 UTC format |
| `taxation` | object or null | Taxation information Bolta last checked. `null` when unknown |
| `taxation.type` | string | Tax type |

## Status values

### Business kind

| Kind (`businessKind`) | Meaning |
| - | - |
| `INDIVIDUAL` | Sole proprietor |
| `CORPORATE` | Corporation |

### Registration state and tax type

`registration.status` and `taxation.type` use the same values and meanings as the status values of [Business Registration Status](/en/docs/api-introduction/business-registration-status). Treat any value you do not recognize as other.

`registration` and `taxation` hold the values Bolta last checked and stored, and `registration.checkedAt` holds the time of that check. When you need the state at call time, use the [Business Registration Status](/en/docs/api-introduction/business-registration-status) API.

## Test key

A test key returns fixed mock data instead of reading real business data. The response structure matches a live key, and no points are deducted.

### Test numbers for profile retrieval

| Number | `businessKind` | `registration.status` | `taxation.type` | Note |
| - | - | - | - | - |
| `1000000014` | `CORPORATE` | `ACTIVE` | `GENERAL` | Example with every field filled |
| `1000000028` | `INDIVIDUAL` | `ACTIVE` | `SIMPLIFIED_RECEIPT_ISSUER` | |
| `1000000106` | `INDIVIDUAL` | `ACTIVE` | `SIMPLIFIED_TAX_INVOICE_ISSUER` | |
| `1000000033` | `INDIVIDUAL` | `ACTIVE` | `TAX_FREE` | |
| `1000000047` | `CORPORATE` | `ACTIVE` | `NONPROFIT` | |
| `1000000052` | `CORPORATE` | `ACTIVE` | `UNIQUE_NUMBER_ORGANIZATION` | |
| `1000000066` | `INDIVIDUAL` | `SUSPENDED` | `GENERAL` | |
| `1000000071` | `INDIVIDUAL` | `CLOSED` | `GENERAL` | `registration.closedOn` is January 1, 2026 (fixed) |
| `1000000085` | `INDIVIDUAL` | `NOT_REGISTERED` | null (`taxation` is null) | |
| `1000000090` | `INDIVIDUAL` | `UNKNOWN` | null (`taxation` is null) | |
| `1000000111` | `INDIVIDUAL` | null (`registration` is null) | null (`taxation` is null) | Example of a state never checked. `address` is also `null` |
| `1000000125` | - | - | - | Number with no profile. `404 NOT_FOUND` |

* `registration.checkedAt` is `2025-12-31T15:00:00Z` (fixed) for every number.
* Only numbers whose `businessKind` is `CORPORATE` have a corporation registration number and a corporation establishment date.
* Only `1000000014` has contact details, an English business name, a former business name, and a mail-order business report number.
* For a number that is also a [Business Registration Status](/en/docs/api-introduction/business-registration-status) test number, both APIs return the same registration state and tax type.

### Test data for search

There are 25 mock businesses, and every business name starts with `테스트상사`. They are the 11 numbers above that have a profile, plus 14 businesses named `테스트상사 01호점` to `테스트상사 14호점`. The 14 businesses are active sole proprietors whose `taxation.type` is `GENERAL`.

A test key search finds businesses whose business name contains the keyword, or whose business registration number equals it. Check representative name, initial consonant, and region name searches with a live key.

* `keyword=테스트상사` returns all 25 businesses.
* Call with `limit=10` to try receiving the results in three calls through `nextCursor`.
* `excludeStatuses=SUSPENDED,CLOSED` removes `1000000066` and `1000000071`.
* A keyword that matches no business returns empty `items`.

You can retrieve the profile of all 25 businesses, and the search result and the profile of the same number hold the same values. If you retrieve any other number with a test key, the API returns `400` with `INVALID_REQUEST`.

## Rate limits

| Path | Limit |
| - | - |
| Search | 120 calls per minute |
| Profile retrieval | 300 calls per minute |

The limit counts calls, not results. Keys of the same partner in the same mode share the limit, and test keys and live keys are counted separately.

When you exceed the limit, the API returns `429` with `RATE_LIMITED` and puts the seconds until you can retry in the `Retry-After` header. Wait that long before you call again.

## Errors

| Status code | Error code | Condition |
| - | - | - |
| `400` | `INVALID_REQUEST` | Missing `keyword` or a keyword that breaks the rules, `limit` out of range, an empty, duplicated, or unsupported `excludeStatuses` value, a business registration number that is not ten digits, or a number outside the test list with a test key |
| `400` | `INVALID_BUSINESS_REGISTRATION_NUMBER` | Checksum mismatch on profile retrieval |
| `400` | `INVALID_CURSOR` | Malformed cursor, a cursor whose search conditions or key mode differ from when it was issued, or a stale cursor |
| `401` | - | API key authentication failed. No response body |
| `402` | `PAYMENT_REQUIRED` | Insufficient point balance. Top up in the developer center |
| `404` | `NOT_FOUND` | Number with no profile on profile retrieval |
| `409` | `AVAILABLE_POINTS_INSUFFICIENT` | Not enough points available right now because other requests are in progress. Top up, or retry after they finish |
| `429` | `RATE_LIMITED` | Rate limit exceeded. Comes with a `Retry-After` header |
| `500` | `INTERNAL_SERVER_ERROR` | Internal server error |
| `503` | `LOOKUP_UNAVAILABLE` | Search or retrieval is unavailable right now. Retry later |
| `503` | `SERVICE_UNAVAILABLE` | Temporary internal API communication error |

See [Error codes](/en/docs/api-introduction/error-codes) for the full list.

## Related documents

* [Search Business Profiles API](/en/api-reference/business-profile/search-business-profiles)
* [Retrieve Business Profile API](/en/api-reference/business-profile/retrieve-business-profile)
* [Pricing](/en/docs/api-introduction/pricing)
* [Business registration status](/en/docs/api-introduction/business-registration-status)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.