JSON API for European VAT number validation

This service provides a web developer friendly JSON API, making it simple for you to perform European VAT number validation.

You can create an account to access the EU VAT JSON API for use with your own apps. The API service comes with the option to batch check a list of EU VAT numbers and receive an email with the results in a CSV file.

Current VIES status: VIES response time is 0.25 seconds, which is great.

Existing customer? Sign in here to manage your account.


Background

When you make business-to-business transactions you need to validate your customer's VAT number, for tax purposes. European Commission operates a service that allows for validating VAT numbers of European companies. This system is called the VAT Information Exchange System (VIES).

VIES has a free web form (for manual VAT validation) and a SOAP service, which makes it possible to make automated requests for validating VAT numbers.

VIES is often slow or not responding, and SOAP services are tedious and complicated to deal with. When VIES is really stressed it replies with error messages, and sometimes it will even send protocol invalid replies to SOAP requests. So, you'll surely prefer the simple and reliable JSON API service available here.

This API service acts as a robust layer between your app and VIES, and by automatically retrying failed requests multiple times, you will experience fewer failed VAT validation requests. A nice benefit for your customers.

This inexpensive service is available for every company that needs an easy way to automatically validate EU VAT numbers. It has been serving companies such as Shapeways, Envato, Elasticsearch, Fanbooster, and many more around the world for years, as a stable and reliable gateway to VIES.

Nobody says it better than actual customers, here is Rachel Andrew from edgeofmyseat.com:

We were getting a tonne of support requests due to failed VAT number lookups before switching and they have now gone way.

Get access to the EU VAT JSON API

You can create an account and buy access to use the API service from your apps. The price starts at 0.03 EUR 0.015 EUR pr request using pre-paid credits, with volume discounts.

When you create an account and buy API request credits, you get an API key that provides full access to this service.

Create account

The API service comes with the option to batch check a list of EU VAT numbers and receive an email with the results in an Excel compatible CSV file.


The JSON API

The API is simple, just send a HTTP request to:

  https://nephics.com/euvat/<VAT number>?key=<API key>

and you will receive a JSON encoded reply containing the response from VIES.

You can (optionally) include the jsonp query parameter to receive a JSONP response, i.e., a response with content type application/javascript performing a custom callback with the result.

See examples of requests and responses below.

Please note: Without a valid API key, the API server only accepts the example requests, exactly as they are shown below. When you create an account you'll receive an API key, and get full access to the service.

Example request for validating a VAT number

Send a HTTP GET request to the URL:

https://nephics.com/euvat/SE556785615701?key=961b2f0b

The following response is returned (formatted for readability):

  {
    "name": "Nephics AB",
    "countryCode": "SE",
    "vatNumber": "556785615701",
    "valid": true,
    "requestDate": "2015-01-08",
    "address": "LARS OLS V\u00c4G 9 \n218 51 KLAGSHAMN",
    "requestStats": {
        "total": 1.14,
        "retries": 0,
        "queued": 0.0,
        "request": 1.14
    }
  }

If the VAT number is invalid the response will contain valid=false, as seen here, trying to validate VAT number "GB0000000":

  {
    "valid": false,
    "requestDate": "2015-01-08",
    "countryCode": "GB",
    "vatNumber": "0000000",
    "requestStats": {
        "total": 0.1,
        "retries": 0,
        "queued": 0.0,
        "request": 0.1
    }
  }

The requestStats object provides some performance statistics for the request:

If a cached result exists that is not older than 24 hours, the cached result is returned, and the response will contain cachedResult = true.

If the VIES service is down, a HTTP 50x error response is returned with a description of the error. For example:

  {"code": 503, "error": "Member State service unavailable."}

If the request is malformed, e.g. missing the country code, a HTTP 400 error response is returned with a description of the error. For example:

  {"code": 400, "error": "Invalid country code."}

Example JSONP request for validating a VAT number

Send a HTTP GET request as above, but include the jsonp parameter with the function name:

  https://nephics.com/euvat/SE556785615701?key=<API key>&jsonp=myfunc

Response (formatted for readability):

  myfunc({
    "name": "Nephics AB", "countryCode": "SE",
    "vatNumber": "556785615701", "valid": true,
    "requestDate": "2013-04-17",
    "address": "LARS OLS V\u00c4G 9 \n218 51 KLAGSHAMN"
  })

Choose between direct or async request

The API gives you the choice to either 1) wait for the API server to reply with the VAT response, or 2) get an asynchronous callback to your server, when the response is available from VIES.

The first option, as demonstrated with the examples above, is great for front-end code (running in the browser) or for simple server-side request handling, where you don't have the option or infrastructure for receiving a HTTP callback.

The second (async) option is better for a server-side VAT lookup during payment processing, or when you are running an async web server like Node.js or Tornado.

The async option has one major advantage, namely that the callback to your server will occur when the VAT response is ready from VIES. Hence, if VIES is down or not responding, the API server will wait for VIES to get back online, before retrying the request and making the callback to your server.

It happens regularly that VIES is down, though often for shorter periods. Hence, the async option provides a much higher certainty for getting the VAT response from VIES instead of an error message.

Making an async request (advanced use)

Send a HTTP POST request to

  https://nephics.com/euvat/<VAT number>?key=<API key>

with the callback URL in the request body. The provided URL will receive a HTTP POST request with the JSON encoded response from VIES.


Questions and Answers

What are the valid country codes?

The European VAT numbers that can be validated using this API starts with one of these two letter country codes:

  countries = {
    "AT": "Austria",
    "BE": "Belgium",
    "BG": "Bulgaria",
    "CY": "Cyprus",
    "CZ": "Czech Republic",
    "DE": "Germany",
    "DK": "Denmark",
    "EE": "Estonia",
    "EL": "Greece",
    "ES": "Spain",
    "FI": "Finland",
    "FR": "France",
    "GB": "United Kingdom",
    "HR": "Croatia",
    "HU": "Hungary",
    "IE": "Ireland",
    "IT": "Italy",
    "LT": "Lithuania",
    "LU": "Luxembourg",
    "LV": "Latvia",
    "MT": "Malta",
    "NL": "The Netherlands",
    "PL": "Poland",
    "PT": "Portugal",
    "RO": "Romania",
    "SE": "Sweden",
    "SI": "Slovenia",
    "SK": "Slovakia"
  }

Are VAT validation requests cached?

Indeed, VAT replies are cached. A cached result is returned when a cached result exists that is not older than 24 hours. In this case, the response will contain cachedResult=true.

You can get a request a cached result, even when it is older than 24 hours, by setting the query parameter stale_ok=true.
Example:

  https://nephics.com/euvat/SE556785615701?key=<API key>&stale_ok=true

You can force the server always perform the VIES request, even if a cached result exists, by setting the query parameter no_cache=true.
Example:

  https://nephics.com/euvat/SE556785615701?key=<API key>&no_cache=true

Why isn't this service free?

You can use the European Commission's VIES web interface and SOAP service for free, see links above.

VIES is critical for verifying financial transactions between businesses. The JSON API service provides real value to businesses in the form of robustness, ease of use and simplicity.

This being a paid service makes it possible for me to spend time improving the product, provide support and ensure the continuity of the service.

Can I get support?

The API service includes free email support. Email your support questions to: euvat@nephics.com