VIES API Guide: How to Use the EU VAT Validation Service

VIES (VAT Information Exchange System) is the European Commission's service for validating VAT identification numbers across EU member states. If you're building anything that handles B2B transactions in Europe, you'll likely need to interact with it, directly or through a wrapper. This guide covers how VIES works, where it falls short, and how to work around its limitations.

What is VIES?

VIES is operated by the European Commission's Directorate-General for Taxation and Customs Union (DG TAXUD). It provides a centralized interface to check whether a VAT number is registered and active in any of the 27 EU member states.

When you submit a VAT number to VIES, it doesn't check its own database. Instead, it routes the request to the national tax authority of the relevant member state (e.g., Germany's BZSt, France's DGFiP, Italy's Agenzia delle Entrate). Each country maintains its own database and service. VIES is the routing layer.

This architecture is important to understand because it means VIES availability depends on 27 independent national services, not one central system.

How the VIES SOAP API works

VIES exposes a SOAP endpoint at https://ec.europa.eu/taxation_customs/vies/services/checkVatService. The primary operation is checkVat, which takes a country code and VAT number:

<!-- Request -->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:urn="urn:ec.europa.eu:taxud:vies:services:checkVat:types">
  <soapenv:Body>
    <urn:checkVat>
      <urn:countryCode>FR</urn:countryCode>
      <urn:vatNumber>82542065479</urn:vatNumber>
    </urn:checkVat>
  </soapenv:Body>
</soapenv:Envelope>

<!-- Response -->
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <checkVatResponse xmlns="urn:ec.europa.eu:taxud:vies:services:checkVat:types">
      <countryCode>FR</countryCode>
      <vatNumber>82542065479</vatNumber>
      <requestDate>2026-03-17+01:00</requestDate>
      <valid>true</valid>
      <name>EXAMPLE SAS</name>
      <address>1 RUE DE RIVOLI 75001 PARIS</address>
    </checkVatResponse>
  </soap:Body>
</soap:Envelope>

There's also a checkVatApprox operation that performs a fuzzy match against a trader's name and address, but availability varies by country and results are inconsistent.

VIES limitations developers hit in practice

Per-country downtime

Because VIES routes to national services, individual countries can go offline independently. The European Commission publishes a member state availability schedule, but unplanned outages are common. Italy and Spain are historically the least reliable. When a country's service is down, VIES returns a SOAP fault. Your code needs to handle this gracefully.

SOAP complexity

SOAP is verbose and requires XML parsing. Most modern languages have moved away from native SOAP support. In JavaScript/TypeScript, you'll need to either construct XML strings manually or use a library like soap or fast-xml-parser. In Python, zeep works but adds a heavy dependency.

No batch validation

VIES only supports one VAT number per request. If you need to validate a list of numbers (e.g., during a data migration or bulk invoice run), you need to make sequential requests and handle rate limiting yourself.

Rate limiting without documentation

VIES applies rate limits, but they're not documented. The limits appear to be per-IP and vary. If you exceed them, you get a SOAP fault with the code MS_MAX_CONCURRENT_REQ. There's no Retry-After header or clear guidance on backoff.

No UK support

Since the UK left the EU on January 31, 2020, UK VAT numbers are no longer in VIES. To validate GB-prefixed numbers, you need a separate integration with HMRC's VAT Registered Companies API, which has its own authentication (OAuth 2.0), rate limits, and response format.

Common VIES error scenarios

Here are the SOAP faults you'll encounter and what they mean:

• INVALID_INPUT: The VAT number format is wrong (e.g., wrong length, invalid country code). Validate format client-side before calling VIES.
• MS_UNAVAILABLE: The member state's service is down. You should cache and retry later.
• MS_MAX_CONCURRENT_REQ: Rate limited. Back off and retry.
• TIMEOUT: The member state didn't respond in time. VIES has an internal timeout; some countries are slower than others.
• SERVICE_UNAVAILABLE: VIES itself is down (not a specific country). Rare but it happens during maintenance windows.

How Vatly solves these problems

Vatly wraps VIES, HMRC, the BFS UID Register, the Bronnysund Register, and the Australian ABR in a REST API that handles the infrastructure you'd otherwise build yourself:

• REST + JSON: Standard HTTP GET with JSON responses. No XML parsing.
• Built-in caching: 25-day response cache. If VIES is down for a country, cached results are returned with meta.cached: true.
• EU, UK, CH, LI, NO, and AU in one endpoint: Vatly detects the country prefix and routes to VIES, HMRC, BFS, Bronnysund, or ABR automatically. One API key, one response format, 32 countries.
• Structured errors: Machine-readable error codes instead of SOAP faults. Every error includes a code, message, and HTTP status.
• Test mode: Use magic VAT numbers with a test API key to simulate valid, invalid, and error responses. No live service calls.
• Rate limit transparency: Clear rate limits per tier, documented, with X-RateLimit-* headers on every response.

A typical request:

curl https://api.vatly.dev/v1/validate?vat_number=FR82542065479 \
  -H "Authorization: Bearer vtly_live_your_api_key"

See the full API documentation for response schemas, error codes, and SDK examples.

Get started

Vatly's free tier includes 500 validations per month with the same API and caching as paid plans. No credit card required.

Try Vatly free →