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: [email protected]]"    
  }
}
                


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.


Business Continuity - API Overages

Ensuring our customers achieve success is paramount to what we do at APILayer. For this reason, we will be rolling out our Business Continuity plan guaranteeing your end users will never see a drop in coverage. Every plan has a certain amount of API calls that you can make in the given month. However, we would never want to cut your traffic or impact user experience negatively for your website or application in case you get more traffic.

What is an overage?

An overage occurs when you go over a quota for your API plan. When you reach your API calls limit, we will charge you a small amount for each new API call so we can make sure there will be no disruption in the service we provide to you and your website or application can continue running smoothly.

Prices for additional API calls will vary based on your plan. See table below for prices per call and example of an overage billing.

Plan Name Monthly Price Number of Calls Overage Price per call Overage Total price
Basic $9.99 1,000 0.014985 500 $17.48
Professional $29.99 4,000 0.01124625 2,000 $52.48
Enterprise $99.99 20,000 0.00749925 10,000 $174.98

Why does APILayer have overage fees?

Overage fees allow developers to continue using an API once a quota limit is reached and give them time to upgrade their plan based on projected future use while ensuring API providers get paid for higher usage.

How do I know if I will be charged for overages?

When you are close to reaching your API calls limit for the month, you will receive an automatic notification (at 75%, 90% and 100% of your monthly quota). However, it is your responsibility to review and monitor for the plan’s usage limitations. You are required to keep track of your quota usage to prevent overages. You can do this by tracking the number of API calls you make and checking the dashboard for up-to-date usage statistics.

How will I be charged for my API subscription?

You will be charged for your monthly subscription plan, plus any overage fees applied. Your credit card will be billed after the billing period has ended.

What happens if I don’t have any overage fees?

In this case, there will be no change to your monthly invoice. Only billing cycles that incur overages will see any difference in monthly charges. The Business Continuity plan is an insurance plan to be used only if needed and guarantees your end users never see a drop in coverage from you.

What if I consistently have more API calls than my plan allows?

If your site consistently surpasses the set limits each month, you may face additional charges for the excess usage. Nevertheless, as your monthly usage reaches a certain threshold, it becomes more practical to consider upgrading to the next plan. By doing so, you ensure a smoother and more accommodating experience for your growing customer base.

I would like to upgrade my plan. How can I do that?

You can easily upgrade your plan by going to your Dashboard and selecting the new plan that would be more suitable for your business needs. Additionally, you may contact your Account Manager to discuss a custom plan if you expect a continuous increase in usage.


Introducing Platinum Support - Enterprise-grade support for APILayer

Upgrade your APIlayer subscription with our exclusive Platinum Support, an exceptional offering designed to enhance your business’ API management journey. With Platinum Support, you gain access to a host of premium features that take your support experience to a whole new level.

What does Platinum Support include?

Standard Support Platinum Support
General review on the issue
Access to knowledge base articles
Email support communication
Regular products updates and fixes
Dedicated account team
Priority Email Support with unlimited communication
Priority bug and review updates
Option for quarterly briefing call with product Management
Features requests as priority roadmap input into product

Priority Email Support: Experience unrivaled responsiveness with our priority email support. Rest assured that your inquiries receive top-priority attention, ensuring swift resolutions to any issues.

Unlimited Communication: Communication is key, and with Platinum Support, you enjoy unlimited access to our support team. No matter how complex your challenges are, our experts are here to assist you every step of the way.

Priority Bug Review and Fixes: Bugs can be a headache, but not with Platinum Support. Benefit from accelerated bug review and fixes, minimizing disruptions and maximizing your API performance.

Dedicated Account Team: We understand the value of personalized attention. That's why Platinum Support grants you a dedicated account team, ready to cater to your specific needs and provide tailored solutions.

Quarterly Briefing Call with Product Team: Stay in the loop with the latest updates and insights from our Product team. Engage in a quarterly briefing call to discuss new features, enhancements, and upcoming developments.

Priority Roadmap Input: Your input matters! As a Platinum Support subscriber, your feature requests receive top priority, shaping our product roadmap to align with your evolving requirements.

Don't settle for the standard when you can experience the exceptional. Upgrade to Platinum Support today and supercharge your APIlayer experience!