Developers API Documentation

1. Introduction

This API is part of the VAT Suite service.
The API provides validation and company information about a VAT (Value Added Tax) number.
The service returns details such as the registration status, company information, and address associated with the provided VAT number.

Endpoint

The API endpoint for accessing the VAT information is: https://api.bav.com/validate/

---

2. Request

HTTP Method

The API supports HTTP GET and HTTP POST requests.

Request Parameters

The API expects the following parameters to be included in the request:

Parameter	Type	Description
api_key	string	Your personal API key required to authenticate you with the service.
vat	string	The VAT number to query.

Sample Request

curl "https://api.bav.com/validate/" \
    -X POST \
    -d api_key=[YOUR_API_KEY] \
    -d vat=BE0567647463

---

3. Response

Response Format

The API returns a JSON object with the following fields:

Field	Type	Description
query	object	Information about the query request.
valid	boolean	Indicates whether the VAT number is valid.
active	boolean	Indicates whether the VAT number is active.
registration_data	object	Company registration data associated with the VAT number.
error	object	Error details if any occurred during the request.

Response Fields

query

The query object contains information about the query request.

Field	Type	Description
vat	string	The VAT number queried.
status	string	The status of the query. Possible values: 'completed', 'processing'. A status with value 'processing' indicates the local VAT registry for the respective country is not responding. In this case the request should be retried later. An error will be present with status 202 and message "National registry not responding. Try again later."
request_time	string	The time of the request.

valid

The valid field indicates whether the VAT number is valid.
This indicates the VAT number passed the passive checks: check digit, format, length and structure.

Field	Type	Description
valid	boolean	true if the VAT number is valid, false otherwise.

active

The active field indicates whether the VAT number is active.
Active vat indicates that the VAT number is registered and operational with the local country's VAT registry.

Field	Type	Description
active	boolean	true if the VAT number is active, false otherwise.

registration_data

The registration_data field contains company registration data associated with the VAT number.

Field	Type	Description
name	string	The name of the registered company.
address	string	The registered address of the company.
city	string	The city of the registered company.
zip	string	The ZIP or postal code of the company.
country_iso	string	The ISO code of the country (e.g., "BE" for Belgium).
country_name	string	The name of the country (e.g., "Belgium").

error

The error field contains details if any error occurred during the validation process.

Field	Type	Description
code	string	A code representing the error type or category.
message	string	A brief error message.

Sample Response

JSON
{
	"query": {
		"vat": "FR64443061841",
		"status": "completed",
		"request_time": "2023-05-30 09:29:08"
	},
		"valid": true,
		"active": true,
		"registration_data": {
		"name": "EURL GOOGLE FRANCE",
		"address": "8 RUE DE LONDRES",
		"city": "PARIS",
		"zip": "75009",
		"country_iso": "FR",
		"country_name": "France"
	},
	"error": {}
}

---

4. Error Handling

If an error occurs during the request, the API may return an appropriate HTTP status code along with an error response in the JSON format. Common error fields may include:

Error Code	HTTP Status	Message	Cause/Solution
301	403	API Key is invalid	You need to provide a correct API key to use the service.
305	403	You have no access to this API	You need to purchase a plan to use this service.
304	403	IP Address not allowed	You have enabled IP address access list. You need to allow your IP to access the API.
302	403	Subscription expired	You need to renew your plan.
303	403	No queries available	You need to refill your plan. You can purchase a package from your Client Area.
306	400	Bad Request: Missing 'api_key' parameter value	You need to submit an API key with your query.
307	400	Bad Request: Missing 'vat' parameter value	VAT parameter is required. You need to submit it for your query to succeed.
500	500	Internal Server Error	Contact support. The error is caused by a technical issue on our end.
603	422	VAT number cannot be shorter than 4 characters.	There are no VAT IDs shorter than 4 digits. Please check your input.
601	422	Invalid characters in VAT number.	VAT IDs can only contain Alphanumeric characters e.g. a-z, A-Z, 0-9. Characters: Underscore:_, Dash:-,Space: , Dot:. are cleaned from the input string. All other characters will trigger this order.
602	422	Country code not supported.	The country code in the VAT ID is not valid. Eg. VAT is not valid.
604	422	Invalid VAT format, length, structure or check digit.	The VAT ID has failed one of our passive formatting and mathematical algorithm checks. It is invalid.
503	503	National registry not responding. Try again later.	The tax register of the respective country is not responding. You need to retry this lookup again. Your account will not be credited.
429	429	Too many requests. Rate limit reached.	Our API is rate limited to provide optimal performance. Please throttle your requests.

Ensure to handle error responses gracefully and provide appropriate feedback to users.