EU VAT Batch Validator (VIES)

Validate EU VAT numbers in bulk against the official VIES service run by the European Commission — and get a straight answer even when a member state's server is down.

Why this exists

VIES is the only authoritative source for EU VAT validation, but it has a well-known problem: individual member states go offline regularly. When Germany's node is down, VIES returns MS_UNAVAILABLE — and most tools quietly treat that as "invalid" or just fail the row.

That's a dangerous mistake. A VAT number that could not be checked is not an invalid VAT number. If you block a customer, refuse a reverse-charge invoice, or drop a lead because of it, the error is yours.

This Actor never conflates the two:

Result	What it means
VALID	VIES confirmed it, with the registered name and address
INVALID	VIES actively said this number is not registered
MS_UNAVAILABLE / TIMEOUT	The member state did not answer. Retried with exponential backoff first. Treat as "unknown", not "invalid"
UNKNOWN_COUNTRY	No EU country prefix found — and we don't charge you for these

What it does

• Bulk — pass a list, it validates them concurrently (default 4 parallel, tunable)
• Forgiving input — IE6388047V, IE 6388047 V, ie-6388047v all work. GB is mapped to XI (Northern Ireland) automatically, since Great Britain left VIES after Brexit
• Automatic retries — member-state outages are retried with exponential backoff and jitter before giving up
• Structured output — country, number, status, validity, registered name, registered address, attempt count, timestamp

Input

{
  "vatNumbers": ["IE6388047V", "NL810195835B01", "FR40303265045"],
  "defaultCountry": "",
  "concurrency": 4,
  "maxRetries": 4
}

defaultCountry is used for numbers with no prefix (e.g. 6388047V with defaultCountry: "IE").

Output

{
  "input": "IE6388047V",
  "countryCode": "IE",
  "vatNumber": "6388047V",
  "status": "VALID",
  "isValid": true,
  "name": "GOOGLE IRELAND LIMITED",
  "address": "3RD FLOOR, GORDON HOUSE, BARROW STREET, DUBLIN 4",
  "attempts": 1,
  "checkedAt": "2026-09-23T00:00:00.000Z",
  "error": null
}

A SUMMARY record (total / valid / invalid / unresolved) is written to the key-value store.

Pricing

Pay per event. You are charged only for numbers actually submitted to VIES — empty rows and numbers with no recognisable EU country prefix are filtered out for free, and retries of a single number count as one charge.

Coverage

All 27 EU member states plus XI (Northern Ireland). Data comes directly from VIES; this Actor does not cache or resell results.

Notes

• VIES is a government service with its own rate limits. Keep concurrency modest (4–6) for large batches.
• VIES returns the registered name and address only for member states that choose to publish them; some return ---, which this Actor normalises to null.