> ## 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 Registration Status

> Input rules and responses for the API that checks the registration status and tax type of one or many business registration numbers.

## What this API returns

This API returns the registration status and tax type of a business registration number. You can tell whether the business is active, suspended, closed, or not registered at all.

| Endpoint                                          | Use                             |
| ------------------------------------------------- | ------------------------------- |
| `POST /v1/businessRegistrationStatuses:check`     | Check one number                |
| `POST /v1/businessRegistrationStatuses:checkBulk` | Check up to 100 numbers at once |

Use the bulk endpoint when you check many numbers, such as a customer list. Both endpoints return the same states and tax types.

<Info>
  This API requires no issuer registration and no certificate. Call it with an API key alone.
</Info>

Unlike the tax invoice APIs, these endpoints do not use `Bolta-Client-Reference-Id` and provide no idempotency key.

## Single lookup

### Request

| Header          | Required | Description                                                                               |
| --------------- | -------- | ----------------------------------------------------------------------------------------- |
| `Authorization` | O        | Set `Basic {apiKey}`. See the [authentication guide](/en/api-introduction/authentication) |
| `Content-Type`  | O        | `application/json`                                                                        |

```bash theme={"dark"}
curl -X POST https://xapi.bolta.io/v1/businessRegistrationStatuses:check \
  -H "Authorization: Basic {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{ "businessRegistrationNumber": "1000000014" }'
```

Enter a ten-digit business registration number. Hyphens are allowed, as in `100-00-00014`. The API validates the format and the checksum, and the response carries ten digits with hyphens removed.

Your API key determines whether the lookup runs in test or live mode. Do not set the mode in the request body or a header.

### Response

```json theme={"dark"}
{
  "businessRegistrationNumber": "1000000014",
  "registration": {
    "status": "ACTIVE",
    "closedOn": null
  },
  "taxType": "GENERAL"
}
```

| Field                        | Type           | Description                         |
| ---------------------------- | -------------- | ----------------------------------- |
| `businessRegistrationNumber` | string         | Ten digits with hyphens removed     |
| `registration.status`        | string         | Business registration state         |
| `registration.closedOn`      | string or null | Closing date in `YYYY-MM-DD` format |
| `taxType`                    | string or null | Tax type                            |

The API always returns all three fields, and a missing value is `null`.

## Bulk lookup

### Request

The headers are the same as for a single lookup.

```bash theme={"dark"}
curl -X POST https://xapi.bolta.io/v1/businessRegistrationStatuses:checkBulk \
  -H "Authorization: Basic {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{ "businessRegistrationNumbers": ["1000000014", "100-00-00028", "1000000066"] }'
```

* Put between 1 and 100 numbers in `businessRegistrationNumbers`. For more than 100, split them across several calls.
* Each number follows the same validation as a single lookup. Hyphens are allowed.
* The API rejects the whole request with `400` for an empty array, more than 100 numbers, or any item with an invalid format.
* If a number appears more than once, the API keeps only the first occurrence. Numbers that differ only in hyphens count as the same number.

### Response

```json theme={"dark"}
{
  "results": [
    {
      "businessRegistrationNumber": "1000000014",
      "status": {
        "businessRegistrationNumber": "1000000014",
        "registration": { "status": "ACTIVE", "closedOn": null },
        "taxType": "GENERAL"
      }
    },
    {
      "businessRegistrationNumber": "1000000028",
      "status": {
        "businessRegistrationNumber": "1000000028",
        "registration": { "status": "ACTIVE", "closedOn": null },
        "taxType": "SIMPLIFIED"
      }
    },
    {
      "businessRegistrationNumber": "1000000066",
      "status": {
        "businessRegistrationNumber": "1000000066",
        "registration": { "status": "SUSPENDED", "closedOn": null },
        "taxType": null
      }
    }
  ]
}
```

| Field                                  | Type           | Description                                                                                             |
| -------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------- |
| `results`                              | array          | One item per requested number, in request order after duplicates are removed                            |
| `results[].businessRegistrationNumber` | string         | Ten digits with hyphens removed                                                                         |
| `results[].status`                     | object or null | Same structure as the single lookup response. `null` if the number could not be checked in this request |

When a live key lookup cannot check some numbers in this request, the API sets `status` to `null` for those items. The number below only illustrates the format.

```json theme={"dark"}
{ "businessRegistrationNumber": "1000000028", "status": null }
```

A `null` status does not mean the number is unregistered, so handle it separately from `NOT_REGISTERED`. The other items remain valid. Retry only the `null` numbers after a short wait. Test key responses never contain `null` items.

If the API cannot check any number, it returns `503` with `LOOKUP_UNAVAILABLE` instead of `200`. If the partner call quota is insufficient, or Bolta's service-wide daily lookup limit is reached before any number is checked, it returns `429` with `RATE_LIMITED`. If the service-wide limit is reached partway through, the API returns `200` with the numbers already checked and sets `status` to `null` for the rest.

## Values

### Registration state

| State (`status`) | Meaning                                        |
| ---------------- | ---------------------------------------------- |
| `ACTIVE`         | Active business                                |
| `SUSPENDED`      | Suspended business                             |
| `CLOSED`         | Closed business                                |
| `NOT_REGISTERED` | Unregistered number                            |
| `UNKNOWN`        | Any other registration state not covered above |

<Warning>
  The API never reports a communication failure as `UNKNOWN`. When it cannot check the registration status, it returns `503` with `LOOKUP_UNAVAILABLE`. Handle the two cases separately.
</Warning>

### Tax type

| Tax type (`taxType`) | Meaning             |
| -------------------- | ------------------- |
| `GENERAL`            | General taxpayer    |
| `SIMPLIFIED`         | Simplified taxpayer |
| `TAX_FREE`           | Tax-exempt business |
| `NONPROFIT`          | Nonprofit           |
| `OTHER_CORPORATION`  | Other corporation   |

Only an active business carries a tax type. Every other state returns `null`.

`closedOn` carries a date only for a closed business. Every other state returns `null`.

## Checking with a test key

A test key runs no real lookup. It returns mock responses for the fixed numbers below. The results are fixed values and bear no relation to the real status of any business.

| Number       | `registration.status` | `taxType`           | `registration.closedOn` |
| ------------ | --------------------- | ------------------- | ----------------------- |
| `1000000014` | `ACTIVE`              | `GENERAL`           | null                    |
| `1000000028` | `ACTIVE`              | `SIMPLIFIED`        | null                    |
| `1000000033` | `ACTIVE`              | `TAX_FREE`          | null                    |
| `1000000047` | `ACTIVE`              | `NONPROFIT`         | null                    |
| `1000000052` | `ACTIVE`              | `OTHER_CORPORATION` | null                    |
| `1000000066` | `SUSPENDED`           | null                | null                    |
| `1000000071` | `CLOSED`              | null                | January 1, 2026 (fixed) |
| `1000000085` | `NOT_REGISTERED`      | null                | null                    |
| `1000000090` | `UNKNOWN`             | null                | null                    |

To include hyphens, enter the number as `100-00-00014`. A test key that looks up a number outside this list receives `400` with `INVALID_REQUEST`. A number with an invalid format or checksum is rejected as an input error.

Bulk lookup follows the same rule. If any number outside the list is in the request, the API rejects the whole request with `400` rather than returning that number as a `status: null` item.

<Info>
  Bolta provides no test scenario that forces `402`, `429`, or `503`. Real authentication failures, quota exhaustion, and service outages follow the error handling below.
</Info>

A live key that sends one of these numbers runs a real lookup.

## Pricing

Pricing for the Business Registration Status API is set by separate agreement. Contact your Bolta representative if you are considering it.

## Call quota

Each API key mode can check 10,000 business registration numbers per 24 hours. The quota counts numbers checked, not requests. A bulk lookup with 100 numbers after duplicates are removed uses 100 of the quota at once. The 24-hour window starts at your first call.

* Keys of the same mode under the same partner share one quota.
* Test keys and live keys do not share a quota.

The API also returns `429` when Bolta reaches its service-wide daily lookup limit.

Once the quota is exhausted, the API returns `429` with `RATE_LIMITED` and sets the `Retry-After` header to the seconds remaining. Read that header to schedule your retry.

<Warning>
  Bolta adds no automatic retry to this API. Calling again immediately after a `429` or `503` only drains the quota faster.
</Warning>

## Errors

| Status code | Error code                             | Condition                                                                                                                                                  |
| ----------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`       | `INVALID_REQUEST`                      | Missing number, input that is not ten digits, or a test key looking up a number outside the list. For bulk lookup, an empty array or more than 100 numbers |
| `400`       | `INVALID_BUSINESS_REGISTRATION_NUMBER` | Number with an invalid checksum                                                                                                                            |
| `401`       | -                                      | API key authentication failed. Empty response body                                                                                                         |
| `402`       | `PAYMENT_REQUIRED`                     | Insufficient balance on a live key                                                                                                                         |
| `403`       | `FORBIDDEN`                            | No access to the requested resource                                                                                                                        |
| `429`       | `RATE_LIMITED`                         | Partner call quota or Bolta's service-wide lookup limit exceeded. Includes the `Retry-After` header                                                        |
| `500`       | `INTERNAL_SERVER_ERROR`                | Internal server error                                                                                                                                      |
| `503`       | `LOOKUP_UNAVAILABLE`                   | Cannot check the business registration status. For bulk lookup, no number could be checked                                                                 |
| `503`       | `SERVICE_UNAVAILABLE`                  | Temporary internal API communication error                                                                                                                 |

For the full list, see [Error Codes](/en/api-introduction/error-codes).

## Related documents

* [Check Business Registration Status API](/api-reference/business-registration-status/check-business-registration-status)
* [Check Business Registration Statuses in Bulk API](/api-reference/business-registration-status/check-business-registration-statuses-in-bulk)
* [Authentication guide](/en/api-introduction/authentication)
* [Glossary](/en/api-introduction/glossary)