Validate a VAT number (VIES) when entering an invoice
A mistyped or unregistered VAT number on an intra-community invoice means a reverse charge that can be challenged. The check belongs at data entry, not at closing.
The problem#
When you invoice a client established in another member state under the reverse charge, you have to make sure its VAT number is valid. The European VIES service allows this check, but doing it by hand for every new client, then again when a client changes number, is the kind of task that gets forgotten.
The right moment to check is data entry: in the client creation form, or when the invoice is prepared. An invalid number is then corrected immediately, before the invoice goes out.
The API data that answers it#
GET /vat/{vatNumber}: real-time validation of a European Union VAT number with the VIES service of the European Commission.- The response says whether the number is valid, the country, the normalised number, the date of the request and, when the member state discloses them, the name and address of the holder.
- Input is forgiving:
BE1033022383,BE 1.033.022.383or1033022383(Belgium by default) are accepted. - For a Belgian client,
GET /enterprise/{num}completes the check with the register record (status, legal form, registered office).
Example request#
curl https://companybelgium.be/api/v2/vat/BE1033022383 \
-H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET"Response for a valid number:
{
"success": true,
"data": {
"isValid": true,
"countryCode": "BE",
"vatNumber": "1033022383",
"requestDate": "...",
"name": "...",
"address": "..."
},
"timestamp": "...",
"meta": {
"responseTime": "..."
}
}Recommended implementation#
- Call the validation from your server when the VAT field is filled in, then show the result in the form.
- Offer the name and address returned by VIES as an input aid, without overwriting what the user has already entered.
- Keep the request date with the result: it documents the check made at invoicing time.
- Do not block the invoice when VIES does not answer: flag the check as “to redo” and try again later.
Limits to know#
- VIES is a European Commission service that queries national administrations. When a member state is unavailable, the API answers with a 502 error: it is not an invalid number.
- An unreadable format returns a 400 error without querying VIES.
- Some member states disclose neither name nor address: those fields then come back empty, even for a valid number.
- A number that is valid in VIES proves VAT registration, not the identity of the person placing the order. To open an account, see the KYB case.
- The validation does not replace your own analysis of the VAT treatment of the transaction.
Frequently asked questions#
Which countries does VAT validation cover?
Every member state of the European Union, since the validation goes through the VIES service of the European Commission.
What if VIES does not answer?
The API returns a 502 error. Keep the invoice pending its check or try again later; an unavailable service does not mean the number is invalid.
Is the country prefix required?
Not for a Belgian number: without a prefix, Belgium is used by default. For other countries, include the prefix (FR, NL, DE…).
Put it into practice
Create a key in the developer portal, then follow the reference documentation for each endpoint mentioned.
Reference documentation