EU VAT Number Validation (Official VIES)

Validate EU VAT numbers against VIES, the European Commission's own validation service. No API key, no scraping.

The thing most VAT checkers get wrong

VIES does not answer by itself. It forwards your question to the tax authority of that member state. When that national system is busy or down, VIES replies with HTTP 200 and isValid: false — the same shape as a genuinely invalid number.

A checker that only reads isValid will tell you a perfectly valid French VAT number is invalid. In tax and invoicing work, that is worse than an error.

This Actor separates the two:

Status	Meaning
VALID	Registered for VAT. isValid is true.
INVALID	Not registered. isValid is false.
SERVICE_UNAVAILABLE	The member state did not answer. isValid is empty — unknown, not invalid. Retry later.
INVALID_INPUT	The number could not be read, or VIES rejected the format.

Busy member states are retried with backoff before this is reported.

This is not rare. While building this Actor, Germany's system reported itself as Available in the status endpoint and still answered MS_UNAVAILABLE to every request for several minutes. A checker reading only isValid would have declared a valid German VAT number invalid during that window.

Output

Field	Description
input	What you supplied, unchanged
countryCode, vatNumber	Parsed country and number
status, statusDetail	The four statuses above, with a plain explanation
isValid	true, false, or empty when the service did not answer
name, address	Registered business, where the member state discloses it
requestDate	Timestamp VIES returned

Some countries (Germany among them) do not disclose the name and address. VIES returns --- for those. This Actor leaves the fields empty rather than handing you --- as if it were data.

Input

{
  "vat_numbers": ["IE6388047V", "DE811569869", "FR 40 303 265 045"],
  "max_retries": 3
}

Spaces, dots and dashes are ignored. If your numbers have no country prefix, set country.

Turn on include_country_status to log which member state systems are available before the run — useful when you get SERVICE_UNAVAILABLE and want to know whether it is worth retrying.

Use cases

• Validating customer VAT numbers before issuing zero-rated invoices
• Cleaning a CRM or ERP list of EU business customers
• Periodic re-validation for compliance records
• Enriching leads with the registered business name where available

Limits worth knowing

• VIES is a shared public service. The default pace is two requests per second; going faster makes member state systems refuse requests.
• Availability varies by country and by time of day. SERVICE_UNAVAILABLE is normal and temporary — it is not a defect in your data.
• VIES confirms registration. It does not confirm that a business is trading, nor validate addresses.

Running locally

pip install -r requirements.txt
python -m tests.test_vies

Attribution

Data from VIES, operated by the European Commission. This Actor is not affiliated with or endorsed by the European Commission. VIES results reflect what each member state's system reports at the time of the request.