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

This API requires no issuer registration and no certificate. Call it with an API key alone.

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

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

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

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

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.

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.

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

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.

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

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