Business Registration Status

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.

Call this API with only an API key. You need no issuer registration, certificate, Bolta-Client-Reference-Id, or idempotency key.

Single lookup

Request

Header	Required	Description
`Authorization`	O	Set `Basic {apiKey}`. See the authentication guide
`Content-Type`	O	`application/json`

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

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

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

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

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

UNKNOWN does not mean the lookup failed. When the API cannot check the registration status, it returns 503 with LOOKUP_UNAVAILABLE.

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.

API Introduction

API Guides

Use Cases

SDK / No-code

What this API returns

Single lookup

Request

Response

Bulk lookup

Request

Response

Values

Registration state

Tax type

Checking with a test key

Pricing

Call quota

Errors

​What this API returns

​Single lookup

​Request

​Response

​Bulk lookup

​Request

​Response

​Values

​Registration state

​Tax type

​Checking with a test key

​Pricing

​Call quota

​Errors

​Related documents

What this API returns

Single lookup

Request

Response

Bulk lookup

Request

Response

Values

Registration state

Tax type

Checking with a test key

Pricing

Call quota

Errors

Related documents