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

| 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>
  Call this API with only an API key. You need no issuer registration, certificate, `Bolta-Client-Reference-Id`, or idempotency key.
</Info>

## Single lookup

### Request

| Header          | Required | Description                                                                                    |
| --------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `Authorization` | O        | Set `Basic {apiKey}`. See the [authentication guide](/en/docs/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.

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

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

A `null` status differs from `NOT_REGISTERED`. The other items remain valid, so 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>
  `UNKNOWN` does not mean the lookup failed. When the API cannot check the registration status, it returns `503` with `LOOKUP_UNAVAILABLE`.
</Warning>

### Tax type

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

`taxType` has a value only for an active business, and `closedOn` 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.

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

When a test key looks up a number outside this list, the API returns `400` with `INVALID_REQUEST`. For bulk lookup, one number outside the list rejects the whole request.

## Pricing

Pricing for the Business Registration Status API is set by separate agreement.

## Call quota

Each API key mode can check 10,000 business registration numbers per 24 hours. The quota counts numbers checked after duplicates are removed, not requests. The 24-hour window starts at your first call. Keys of the same mode under the same partner share one quota.

When the quota is exhausted or Bolta reaches its service-wide daily lookup limit, the API returns `429` with `RATE_LIMITED` and sets the `Retry-After` header to the seconds remaining. Read that header to schedule your retry. After a `503`, wait a moment before you check again instead of retrying immediately.

## 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/docs/api-introduction/error-codes).

## Related documents

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