Guides › Validate an EU VAT number in code: Node.js and Python examples
Validate an EU VAT number in code: Node.js and Python examples
Updated
Short answer: Send a GET request to the VATcheckly API with the VAT number and receive JSON with a state of valid, invalid or unavailable. Treat unavailable as unknown and retry later. Add your own VAT number as the requester to get a VIES consultation number for your records.
The official VIES service is SOAP based, throttled per country and returns raw fault codes when a national system is busy. The examples below call a plain JSON endpoint that normalises the number, retries transient errors and returns one of three states.
Node.js (18 or newer)
async function checkVat(vat, requester) {
const url = new URL('https://vatcheckly.com/api/v1/check');
url.searchParams.set('vat', vat);
if (requester) url.searchParams.set('requester', requester);
const res = await fetch(url, {
headers: { Authorization: 'Bearer ' + process.env.VATCHECKLY_KEY },
});
const data = await res.json();
if (res.status === 429) throw new Error('Quota reached: ' + data.error);
return data; // { state: 'valid' | 'invalid' | 'unavailable' | 'format_error', ... }
}
const r = await checkVat('DE123456789', 'FI12345678');
if (r.state === 'valid') console.log(r.name, r.consultation_number);
else if (r.state === 'invalid') console.log('Charge VAT');
else console.log('Unknown, retry later');
Python
import os, requests
def check_vat(vat, requester=None):
params = {"vat": vat}
if requester:
params["requester"] = requester
r = requests.get(
"https://vatcheckly.com/api/v1/check",
params=params,
headers={"Authorization": "Bearer " + os.environ["VATCHECKLY_KEY"]},
timeout=30,
)
return r.json()
result = check_vat("DE123456789", "FI12345678")
print(result["state"], result.get("consultation_number"))
Rules worth following
- Three states, not two.
unavailableis notinvalid. See VIES error codes. - Do not retry in a tight loop when a country is down. Check
/api/v1/status(free) or the live status page. - Store the consultation number with your order or invoice record.
- Keep your key on the server. Never ship it in browser code.
Without a key the endpoint allows 25 requests per day per IP, enough to test the integration. Paid keys start with the Pro plan. Full reference: API docs.
Sources: European Commission: VIES VAT number validation.
Check a VAT number now
Free, live against VIES, all 27 EU countries + Northern Ireland.