API Documentation

vatlayer API

Vatlayer is a simple JSON-based REST API enabling you to validate VAT numbers, retrieve all or single EU VAT rates based on IP address or country code, convert prices in compliance with EU VAT rates and types, and more.

API results are requested using a transparent and easy-to-understand URL structure and delivered in handy JSON format, making for the highest possible level of compatibility with any of your applications, systems, programming languages and frameworks.

The following API documentation explains in detail API properties, parameters and features, provides integration guides and code examples for PHP and jQuery.ajax.


Specs & Overview

API Access Key & Authentication

After signing up, every user is assigned a personal API Access Key - a unique "password" provided to access any of the API's data endpoints (see API Endpoints).

To authenticate with the vatlayer API, simply attach your access_key to your preferred Endpoint URL:

http://apilayer.net/api/validate?access_key=YOUR_ACCESS_KEY  
                

Get your free API Access Key


API Response

All vatlayer API data is returned in easily parseable JSON format. Find below an example API response using the validate endpoint to validate a VAT number.

{
  "valid": true,
  "database": "ok",
  "format_valid": true,
  "query": "LU26375245",
  "country_code": "LU",
  "vat_number": "26375245",
  "company_name": "AMAZON EUROPE CORE S.A R.L.",
  "company_address": "5, RUE PLAETIS L-2338 LUXEMBOURG"
}        
                

Each API endpoint's response properties are explained in the API Features section.


API Endpoints - Quick Overview

The vatlayer API offers 4 main data endpoints, all of which providing different kinds of services and starting out with the following Base URL:

http://apilayer.net/api/

Take a look at the following two API Endpoints: (If you would like to try them out, get a Free Plan and don't forget to attach your Access Key to the URL)

Endpoint 1: Simple VAT number validation

// "validate" endpoint
http://apilayer.net/api/validate
    ? access_key = YOUR_ACCESS_KEY
    & vat_number = VAT_NUMBER
                

Endpoint 2: VAT rate for single EU member state

// "rate" endpoint - via country code  
http://apilayer.net/api/rate
    ? access_key = YOUR_ACCESS_KEY
    & country_code = GB
    
// "rate" endpoint - via custom IP address  
http://apilayer.net/api/rate
    ? access_key = YOUR_ACCESS_KEY
    & ip_address = 176.249.153.36
    
// "rate" endpoint - via client IP address  
http://apilayer.net/api/rate
    ? access_key = YOUR_ACCESS_KEY
    & use_client_ip = 1
                

Endpoint 3: VAT rates for all EU member states

// "rate_list" endpoint 
http://apilayer.net/api/rate_list
    ? access_key = YOUR_ACCESS_KEY
                

Endpoint 4: Price calculation

// "price" endpoint
http://apilayer.net/api/price
    ? access_key = YOUR_ACCESS_KEY
    & amount = 100
    & country_code = GB
                

Each API Endpoint is explained in detail below in the API Features section.


256-bit HTTPS Encryption
Basic Pro Enterprise

Paid Customers may establish a secure connection (industry-standard SSL) to the vatlayer API and all data provided by and accessible through it.

To connect securely, simply attach an s to the HTTP Protocol. (resulting in https://)


API Error Codes

If your query fails, the screenshotlayer API will return a 3-digit error-code, an internal error type and a plain text "info" object containing suggestions for the user.

Find below an example error - triggered when the user did not provide a valid API Access Key:

{
  "success": false,
  "error": {
    "code": 104,
    "type": "invalid_access_key",
    "info": "You have not supplied a valid API Access Key. [Technical Support: support@apilayer.com]"    
  }
}
                


Common API errors:


Type Message Description
404 "404_not_found" User requested a resource which does not exist.
101 "missing_access_key" User did not supply an Access Key.
101 "invalid_access_key" User entered an invalid Access Key.
103 "invalid_api_function" User requested a non-existent API Function.
104 "usage_limit_reached" User has reached or exceeded his Subscription Plan's monthly API Request Allowance.
210 "no_vat_number_supplied" User did not provide a VAT Number.

show all errors


JSONP Callbacks

The vatlayer API also supports JSONP Callbacks. To use this feature, simply attach:

callback = CALLBACK_FUNCTION

to any API Endpoint, and the result set will be returned as the callback function you specified.

Example query:

http://apilayer.net/api/validate?callback=CALLBACK_FUNCTION  
                

Not sure about what JSONP does? Here's a helpful Stack Overflow thread.

Example response:

CALLBACK_FUNCTION ({
{
  "valid": true,
  "database": "ok",
  "format_valid": true,
  "query": "LU26375245",
  "country_code": "LU",
  "vat_number": "26375245",
  "company_name": "AMAZON EUROPE CORE S.A R.L.",
  "company_address": "5, RUE PLAETIS L-2338 LUXEMBOURG"
}        
})                
                

Note: The API also supports Access-Control (CORS) headers.


JSON Formatting

In order to enhance readability the vatlayer API features a built-in JSON format function, which displays the API's Response in typically JSON-structured format.

To enable this function, simply attach format=1 to any valid API Endpoint URL:

http://apilayer.net/api/validate
    ? access_key = YOUR_ACCESS_KEY
    [...]
    & format = 1      
                

Please be aware that enabling format increases the API Response's file size, which might have a negative on your application's performance.


API Features

VAT Number Validation
Free Basic Pro Enterprise

Both free and paid users may perform VAT number validations and company information lookups using the API's validate endpoint.

Simply specify the vat_number you would like to validate and append it to the API request URL.

Example query:

http://apilayer.net/api/validate
    ? access_key = YOUR_ACCESS_KEY
    & vat_number = LU26375245    
                

Example response:

The API's response will consist of a number of different JSON objects containing information about your query, the respective company results and whether or not the validation was successful. Each object will be explained in the table below.

{
  "valid": true,
  "database": "ok",
  "format_valid": true,
  "query": "LU26375245",
  "country_code": "LU",
  "vat_number": "26375245",
  "company_name": "AMAZON EUROPE CORE S.A R.L.",
  "company_address": "5, RUE PLAETIS L-2338 LUXEMBOURG"
}          
                

API response objects:


Object Description
"valid" Contains true if the VAT number you entered could be successfully validated, false if not.
"database" Contains ok if our VAT database sources are currently able to process the requested VAT number, failure if not.
"format_valid" Contains true if the syntax/format of the VAT number you entered is valid, false if not.
"query" Returns the entire VAT number as per your API request.
"country_code" The 2-letter country code assigned to the provided VAT number.
"vat_number" The pure VAT number without the 2-letter country code prefix.
"company_name" The name of the company the VAT number you entered is assigned to.
"company_address" The address of the company the VAT number you entered is assigned to.


VAT Database Status


Since each EU Member State is legally required to keep its VAT number database as up-to-date as possible, regular database updates (which result in temporary downtime of the respective member state's database) are performed.

In order to properly reflect whether or not the requested VAT number can be matched with the responsibe member state's database at the time the API request is made, the vatlayer API returns an additional database JSON object containing "ok" if the respective database can be queried, and "failure", if not.

{
  [...]
  "database": "ok",
  [...]
}        
                

Handling "database": "failure"

If a connection to the respective member state's database cannot be established, hence, if the database object returns "failure", the API's valid object will automatically return false.

{
  "valid": false,
  "database": "failure",
  [...]
}        
                

Important: In order to make use of vatlayer validation results in the most effective and reliable way, it is highly recommended to check whether or not the necessary database connection could be established before taking any actions based on the validation result contained in the API's valid object.


Get VAT Rates via Country Code
Free Basic Pro Enterprise

Using the vatlayer API's rate endpoint, you may request VAT rates for a country of your choice.

Just a quick heads up: There are 3 different parameters that can be used to define the country to obtain VAT rates for. In this example we'll define the country by appending the simple 2-letter country_code parameter to the request URL.

Example query:

http://apilayer.net/api/rate
    ? access_key = YOUR_ACCESS_KEY
    & country_code = DE    
                

Example response:

Along with a success indication and country information, the API's JSON response will consist of a standard_rate, containing the specified country's standard VAT rate (in percent), and a reduced_rates object containing the country's VAT rate exceptions for specific types of goods.

{
  "success": true,
  "country_code": "DE",
  "country_name": "Germany",
  "standard_rate": 19,
  "reduced_rates": {
    "foodstuffs": 7,
    "books": 7,
    "medical": 7,
    "passenger transport": 7,
    "newspapers": 7,
    "admission to cultural events": 7,
    "admission to entertainment events": 7,
    "hotels": 7
  }
}                
                

Please note: In case you provide a country code outside of the European Union, the vatlayer API will not return an error. Instead it will return a VAT rate of 0.


Reduced VAT Rates - Types of Goods


Each country declares individual types of goods that fall into reduced VAT categories, such as medical goods, hotels and books.

You may access a full list containing all available reduced VAT rate types via the API's types endpoint.

Example query:

http://apilayer.net/api/types
    ? access_key = YOUR_ACCESS_KEY
                

Please note: Requesting the API's types endpoint does not count against your monthly API request volume.


Get VAT Rates via IP Address
Free Basic Pro Enterprise

In the previous example we used the API's rate endpoint to request a single country's VAT rates via the country code. In this example we will specify the country by appending a custom ip_address as a query parameter.

Example query:

http://apilayer.net/api/rate
    ? access_key = YOUR_ACCESS_KEY
    & ip_address = 134.245.44.17    
                

Note: In this case, the API response will be identical to the one listed in the previous example. (Get VAT Rates via Country Code)

Note: In case you provide an IP address outside of the European Union, the vatlayer API will not return an error. Instead it will return a VAT rate of 0.


Get VAT Rates via Client IP
Free Basic Pro Enterprise

Additionally to EU VAT rates via the country_code and ip_address parameters, you may also request the API to define the country by using the very IP address the client is using the moment of calling the API.

To have the vatlayer API use the client's IP address as a country reference, simply set the API's use_client_ip parameter to 1.

Example query:

http://apilayer.net/api/rate
    ? access_key = YOUR_ACCESS_KEY
    & use_client_ip = 1    
                

Note: Except for the actual country returned, the API response will be the same as the one provided in the "Get VAT Rates via Country Code" example.

Note: In case the client's IP address is located outside of the European Union, the vatlayer API will not return an error. Instead it will return a VAT rate of 0.


Retrieve all EU VAT Rates
Free Basic Pro Enterprise

Using the vatlayer API's rate_list endpoint, you may also request VAT rates for all 28 EU member states at once.

Example query:

http://apilayer.net/api/rate_list
    ? access_key = YOUR_ACCESS_KEY
                

Important: Please be aware that requesting an entire set of EU VAT rates results in a significantly larger JSON response size than when retrieving a single country's VAT rate, which may have a negative effect on your application's performance. It is highly recommended to request only one country's VAT information at once.


VAT Compliant Price Calculation
Free Basic Pro Enterprise

Using the vatlayer API's price endpoint, you may request the API to calculate VAT compliant prices on your behalf. This API endpoint required two additional query parameters - explained below:

Required parameter: conversion amount

First, you'll need to specify the amount you would like to use for your VAT price calculation:

amount         the amount/price you would like to calculate
               in compliance with EU VAT rates
                

Required parameter: country

As already mentioned above, there are three different parameters that can be used to define the country to obtain VAT rates for. Choose only one of the following:

country_code     define country by appending a two 2-letter
                 country code of your choice
               
ip_address       define country by appending a custom IP
                 address to be located by the API
               
use_client_ip    define country by having the API locate the 
                 IP address of the client making the API call
                

Example query:

http://apilayer.net/api/price
    ? access_key = YOUR_ACCESS_KEY
    & amount = 125
    & country_code = GB
                

Please note: As long as you don't specify an additional type parameter (see advanced options below), the API will automatically calculate your price using the respective country's standard VAT rate.

Example response:

The API response will confirm the country you provided by returing both a country_code and country_name. The amount you entered will be returned as price_excl_vat, and the VAT compliant price will be contained in the price_incl_vat object. Additionally, the vatlayer API will return a vat_rate object containint the EU VAT rate used for your price calculation.

{
  "success": true,
  "country_code": "GB",
  "country_name": "United Kingdom",
  "price_excl_vat": 125,
  "price_incl_vat": 150,
  "vat_rate": 20
}        
                

Advanced VAT Price Calculation Options


The price endpoint also offers two optional parameters:

Optional parameter: type of goods

In case your product falls under the "reduced VAT rates" category you may specify the type of goods according to the API's types endpoint (Learn more).

type      the type of goods according to the 
          API's "types" endpoint
                

Optional parameter: VAT already included

In case you are supplying an amount which already includes the respective VAT percentage and would like to request the API to perform a reverse calculation, simply set the API's incl parameter to 1.

incl      set to 1 if amount already includes 
          VAT percentage
                

Example query:

http://apilayer.net/api/price
    ? access_key = YOUR_ACCESS_KEY
    & amount = 125
    & country_code = GB
    & type = medical
    & incl = 1
                

Example response:

In the United Kingdom there is no VAT rate applying to medical products, therefore the API will return a vat_rate of 0.

{
  "success": true,
  "country_code": "GB",
  "country_name": "United Kingdom",
  "price_excl_vat": 125,
  "price_incl_vat": 125,
  "type": "medical"
  "vat_rate": 0
}                
              

Code Examples

PHP (cURL)

Validate VAT Number:

Find below a simple way of using PHP (cURL) for validating a EU VAT number:

// set API Endpoint and Access Key
$endpoint = 'validate';
$access_key = 'YOUR_ACCESS_KEY';

// set VAT number
$vat_number = 'LU26375245';

// Initialize CURL:
$ch = curl_init('http://apilayer.net/api/'.$endpoint.'?access_key='.$access_key.'&vat_number='.$vat_number.'');  
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Store the data:
$json = curl_exec($ch);
curl_close($ch);

// Decode JSON response:
$validationResult = json_decode($json, true);

// Access and use your preferred validation result objects
$validationResult['valid'];
$validationResult['query'];
$validationResult['company_name'];
$validationResult['company_address'];
                

JavaScript (jQuery.ajax)

Validate VAT Number:

Find below a simple way of using PHP (cURL) for validating a EU VAT number:

// set endpoint and your access key
var endpoint = 'validate'
var access_key = 'YOUR_ACCESS_KEY';
var vat_number = 'LU26375245';

// validate VAT number via AJAX call
$.ajax({
    url: 'http://apilayer.net/api/' + endpoint + '?access_key=' + access_key + '&vat_number=' + vat_number,   
    dataType: 'jsonp',
    success: function(json) {

    // Access and use your preferred validation result objects
    alert(json.valid);
    alert(json.query);
    alert(json.company_name);
    alert(json.company_address);
                
    }
});
                

Please note: In this example, the use of JSONP is entirely optional.