JSON API for European VAT number validation

This software provides a web developer friendly JSON API, making it simple for you to perform European VAT number validation. You can purchase the software to run your own EU VAT JSON API server.

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

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, and when VIES is really stressed, you'll even get protocol invalid replies. So, you'll surely prefer the simple JSON API available with this software.

The sever 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 software is available for everybody to buy and use. It has been serving companies for years, as a stable and reliable gateway to VIES.

The JSON API

The API is simple: Send a HTTP request to:
http://your.vat.server.ip/<VAT number>
and you will receive a JSON encoded reply containing the response from VIES.

See examples of requests and responses below.

Choose between direct or async request

The API gives you the choice to either 1) wait for the 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 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 a direct request

Send a HTTP GET request to http://your.vat.server.ip/<VAT number>, 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.

Making an async request (advanced use)

Send a HTTP POST request to http://your.vat.server.ip/<VAT number> and with callback URL in the body, and the specified URL will receive a HTTP POST request with the JSON encoded response from VIES.

Example requests

The following examples relies on the nephics.com EU VAT JSON API demonstration server, which is only available for the requests shown here.

Example request for validating a VAT number

Send a HTTP GET request to the URL:
http://nephics.com/euvat/SE556785615701

The following response is returned (formatted for readability):

      {
        "name": "Nephics AB",
        "countryCode": "SE",
        "vatNumber": "556785615701",
        "valid": true,
        "requestDate": "2013-08-28",
        "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": "2013-08-28",
          "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 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 country code, a HTTP 400 error response is returned with a description ofthe error. For example:

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

Example JSONP request for validating a VAT number

Send a HTTP GET request to the URL:
http://nephics.com/euvat/SE556785615701?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"
        })

Get your own EU VAT JSON API server

You can buy this powerful software, for use in your company and your own apps. You get the server with source code, and the rights to use and modify it as you please (but, distribution is prohibited). The price is €199 EUR €149 EUR with free email support and 1 year of updates included.

The server software only requires Python 2.7 or 3.3+, which is available pre-installed on any linux server. The API is as described above, but you have the server on your own address.

Buy API server software
or buy access to the nephics.com EU VAT JSON API server.

Questions and Answers

What are thevalid 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?

VAT replies are cached when the server is started with the --cache=/path/to/cache/ command line argument.

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

You can get the cached result, even when it is older than 24 hours, by setting the query parameter stale_ok=true.
Example:
http://nephics.com/euvat/SE556785615701?stale_ok=true

You can force the server to perform the request, even if a cached result exists, by setting the query parameter no_cache=true.
Example:
http://nephics.com/euvat/SE556785615701?no_cache=true

Why isn't this software free?

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

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

You paying a small amount for buying the software makes it possible for me to spend time improving the product, provide support and ensure the continuity of the product.

Can I get support?

The server software includes free email support.
Email your support questions to: euvat@nephics.com