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.
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
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.
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.
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://)
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]]"
}
}
| 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. |
| 105 | "https_access_restricted" | The user's current Subscription Plan does not support HTTPS Encryption. |
| 102 | "inactive_user" | The user's account is not active. User will be prompted to get in touch with Customer Support. |
| 310 | "no_country_code_or_ip_supplied" | User did not provide a Country Code or IP Address. |
| 311 | "both_country_code_and_ip_supplied" | User provided both Country Code and IP Address. Only one of the two can be processed. |
| 410 | "invalid_ip_address" | User provided an invalid IP Address. [Example: 213.162.68.117] |
| 411 | "could_not_resolve_ip" | Our system failed allocating the supplied IP Address. |
| 510 | "invalid_country_code" | User provided an invalid Country Code. (Required format: 2-letter Code - Example: GB) |
| 610 | "invalid_amount" | User provided an invalid "amount" value. (Required format: integer - Example: 10) |
| 611 | "invalid_type" | User provided an invalid "type" value. See Types of Goods. (Example: medical) |
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.
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.
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. |
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.
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.
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.
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.
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.
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.
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
}
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
}
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'];
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.
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.
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.011988 | 500 | $15.98 |
| Professional | $29.99 | 4,000 | 0.008997 | 2,000 | $47.98 |
| Enterprise | $99.99 | 20,000 | 0.0059994 | 10,000 | $159.98 |
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.
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.
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.
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.
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.
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.
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.
| 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!
|
|