Response and errors
API responses are always in JSON format and contain the following fields:
| Name | Type | Description |
|---|---|---|
error | boolean | Indicates whether an error occurred while processing the request |
message | string | Error message or confirmation of successful request |
status | number | HTTP status code of the response |
data | object | Contains the requested data if the request was successful |
timestamp | number | Unix timestamp (in milliseconds) indicating when the response was generated |
eventId | string | Unique ID for the event, useful for tracking requests |
code | string | Internal error code, useful for debugging and reporting issues |
overQuota | boolean | Indicates whether the request has exceeded the monthly quota limit for the API |
You can test the API's behavior in real-time using the playground. Requests made from the playground are not subject to monthly quotas.
Example of a successful response:
Here is a sample excerpt of a successful response for IT00743110157 (Tax type: it_vat):
Available fields in the data object
The data object contains multiple fields, depending on the request and its outcome.
The following properties are always included in the response:
| Name | Type | Description |
|---|---|---|
id | string | The original tax ID provided in the request. |
type | string | The tax type used for verification, e.g., it_vat, gb_vat, etc. |
formattedId | string | The tax ID formatted according to the rules of the corresponding country. |
typeName | string | The name of the tax type in the local language, e.g., Partita IVA, USt-IdNr., etc. |
isValid | boolean | Indicates whether the provided tax ID matches the expected pattern and length. |
isVerified | boolean | Indicates whether the tax ID has been verified via an external data source. |
isPatternOnly | boolean | Indicates whether the tax ID was only checked against the pattern without external verification or logical checks. |
isVerifiable | boolean | Indicates whether the tax ID can be verified using external data sources. |
If the tax ID has been verified against an external data source, or it can be checked manually online, the following additional fields may be included:
| Name | Type | Description |
|---|---|---|
dataSource | string | The source used for verification, e.g., eu-vies, ch-fso, au-abn, etc. |
manualDataSource | string | Name of the website where the tax ID can be manually verified, if applicable. |
If the includeDetails parameter is set to true (default), the following business details may also be included if available:
| Name | Type | Description |
|---|---|---|
firstName | string | The first name of the individual associated with the tax ID, if applicable. |
lastName | string | The last name of the individual associated with the tax ID, if applicable. |
fullName | string | The full name of the individual associated with the tax ID, if applicable. |
birthDate | string | The birth date of the individual associated with the tax ID in the format DD/MM/YYYY, if applicable. |
gender | string | The gender of the individual associated with the tax ID as M or F, if applicable. |
birthPlace | string | The place of birth of the individual associated with the tax ID, if applicable. |
birthCountryCode | string | The country code of birth of the individual associated with the tax ID as per ISO 3166-1 alpha-2, if applicable. |
businessName | string | The registered name of the business associated with the tax ID. |
alternativeName | string | An alternative name or trade name of the business, if available. |
businessType | string | The type of business entity, e.g., LLC, Corporation, etc., if available. |
businessStatus | string | The current status of the business, e.g., Active, Inactive, etc., if available. |
registrationDate | string | The date when the business was registered, in the format DD/MM/YYYY, if available. |
dissolutionDate | string | The date when the business was dissolved, in the format DD/MM/YYYY, if applicable. |
address | string | The street address of the business or individual associated with the tax ID, if available. |
postalCode | string | The postal code of the address associated with the tax ID, if available. |
town | string | The town or city of the address associated with the tax ID, if available. |
region | string | The region or state of the address associated with the tax ID, if available. |
countryCode | string | The country code of the address associated with the tax ID as per ISO 3166-1 alpha-2, if available. |
fullAddress | string | The full address combining street, postal code, town, region, and country, if available. |
alternativeIdentifiers | array | An array of alternative identifiers associated with the business, if available. Each identifier includes: - country: The country code as per ISO 3166-1 alpha-2. - type: The alternative identifier type, if known. - id: The alternative identifier value. |
isVatRegistered | boolean | Indicates whether the business is registered for VAT, if available. |
For your convenience, we have included a Zod schema representing the shape of the response in the Code samples section.
Common error codes
Each error returned by the API includes an error message and an internal error code.
| Internal code | Status | Solution |
|---|---|---|
BAD_REQUEST | 400 | The request is invalid. Check the parameters and the request format. |
MISSING_API_KEY | 401 | The API key was not provided. Make sure to include the API key in the request header under the x-api-key field. |
INVALID_API_KEY | 401 | The provided API key is invalid. Check that the key is correct and active. |
NO_ACTIVE_SUBSCRIPTION | 403 | You do not have an active subscription. Check your subscription from the Profile › Billing section. |
INCOMPLETE_SUBSCRIPTION | 403 | The purchase of your subscription has not yet been completed, go to the billing portal to complete it. |
PAST_DUE_SUBSCRIPTION | 403 | Your subscription has expired. Check your subscription from the Profile › Billing section. |
MONTHLY_QUOTA_EXCEEDED | 429 | You have exceeded the monthly request limit for your plan, and additional requests cannot be charged. You can upgrade to a higher plan or wait until the next month to restore your quota. |
DAILY_LIMIT_EXCEEDED | 429 | You have exceeded the daily request limit for your plan. You can upgrade to a higher plan or wait until the next day to restore your quota. |
BURST_LIMIT_EXCEEDED | 429 | You have exceeded the requests per second limit for your plan. You can upgrade to a higher plan or reduce the frequency of your requests. |
UNEXPECTED_ERROR | 500 | An unexpected error occurred. Please try again later or contact support. |