Skip to navigation
Identity verification APIBusiness Checks

Run a one-off business check

Looks a business up in its registry by registration number. The check runs in the background: the response is 202 with a verificationId, and the result is ready shortly afterwards on the detail endpoint. No webhook is sent for a one-off check.

A requestId you have used before returns the existing check with 202 and runs nothing new.

Sandbox. Outside production the published test numbers return simulated results: RC0000001 is found and RC0000002 is not found. sandboxOutcome pins the result instead. Test checks are never charged.

Billing. Production checks are charged once per lookup. A check that ends in error because of a fault on our side is refunded.

Error codes

errorStatusMeaning
invalid_input400The body failed validation.
product_unsupported400The product does not exist or is not offered for that country.
account_details_required400The product verifies a bank account and account did not carry the holder and number.
subdivision_required400The country registers businesses by region and no subdivisionCode was sent.
subdivision_unsupported400A subdivisionCode was sent for a country with a single registry.
subdivision_unknown400The subdivisionCode is not a supported region for that country.
business_checks_disabled403Business checks are not enabled for your organisation.
secret_key_required403A publishable key was used. This endpoint accepts secret keys only.
environment_mismatch403The key belongs to an environment this deployment does not serve.
ip_not_allowed403The key has an IP allowlist and the calling address is not on it.
organization_suspended403The organisation is suspended. The response carries reason and suspendedAt.
business_not_approved403A live key was used before the business was approved for production.
organization_not_found404The organisation behind the key no longer exists.
rate_limited429The hourly verification limit for your organisation was reached.
pricing_not_configured500No price is configured for this check. Contact support.

A missing or unknown key answers 401, where error is a short sentence rather than a code.

Requires a secret (sk_) key. A publishable key receives 403 secret_key_required.

Authentication

AuthorizationBearer
Send the API key as a Bearer token. Each operation states whether a publishable key is enough or a secret key is required.

Request

This endpoint expects an object.
countrystringRequired=2 characters

The ISO 3166-1 alpha-2 country of the registry.

registrationNumberstringRequired2-64 characters
The registration number to look up. For a product keyed on a tax number, send that number here.
consenttrueRequired
Must be true. You attest that you may run this check.
subdivisionCodestringOptional<=16 characters

The ISO 3166-2 registry region, for example US-DE. Required for countries whose registry is split by region, and refused elsewhere.

registrationNamestringOptional<=200 characters
The registered name you expect, kept with the check for comparison with the name the registry returns.
productstringOptional

The check product. Defaults to business, the standard lookup offered in every supported country. Other products are specific to one country: business-tax, business-taxid and business-tin (NG), business-address and business-account (ZA), business-filings (CI).

externalUserIdstringOptional1-255 characters
Your own reference for the subject. A verified check is recorded against that customer record.
createEntitybooleanOptionalDefaults to true
Whether to save the verified subject as a customer record. Defaults to true. Send false to run the check without creating or updating a record.
accountobjectOptional

The bank account to verify against the registration. Required by the business-account product (South Africa) and ignored by every other product.

sandboxOutcomeenumOptional
Pins the simulated result outside production. Ignored on live keys.
Allowed values:
requestIdstringOptional8-120 characters
Your idempotency key. A retry with the same value returns the same check and never runs or bills a second one.

Response

The check was accepted and is being processed.
verificationIdstring
The id of the check. Read the result from the matching detail endpoint.
statusenum

Always pending at submission. The check is processed in the background.

Allowed values:

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error
500
Internal Server Error