├── README.md └── docs ├── features.md ├── language-examples ├── jquery-ajax.md └── php-curl.md └── specifications.md /README.md: -------------------------------------------------------------------------------- 1 | Stay up to date by following [@apilayernet](https://twitter.com/apilayernet) on Twitter. 2 | 3 | # vatlayer JSON API 4 | 5 | [Vatlayer](https://vatlayer.com) is a free, simple JSON-based REST API allowing 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. 6 | 7 | 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, programming languages and frameworks. 8 | 9 | ## Data Sources 10 | 11 | In order to achieve a high standard of data accuracy and response speed for every API request, the vatlayer API relies on multiple servers and a distinct "fallback & validation" mechanism, consisting of a fairly large number of different data sources (instances), which include the European Commission's databases. 12 | 13 | If one instance fails to deliver an accurate data response (which does not even occur in 99.9% of the cases), the next highest one is assigned with the respective request. Only this way can we provide a consistent service and API living up to our customer's expectations. 14 | 15 | [Sign up for for free](https://vatlayer.com/product) to get instant API Access. 16 | 17 | ## Features & Integration 18 | 19 | At vatlayer we aim to take the headache out of VAT number validation and EU VAT rate retrieval, offering a generous, full-featured **Free Plan** for anybody requiring less than 100 monthly requests or intending to try out the service, and three highly cost-effective premium subscriptions starting at only $9.99 per month. 20 | 21 | The main API Functionalities are: 22 | 23 | * **VAT Number Validation**: 24 | Instantly validate any EU VAT number and retrieve valuable information about the company which it is assigned to. 25 | 26 | * **EU VAT rates**: 27 | Get a single country's VAT rates or request an entire list of VAT rates for all 28 current EU member states. 28 | 29 | * **Standard & Reduced Rates**: 30 | Make use of a EU member state's standard VAT percentage or integrate type-specific reduced VAT rates. (e.g. "medical" products) 31 | 32 | * **VAT Compliant Price Calculation**: 33 | Request the API to perform a country- & type-specific price calculation on your behalf. 34 | 35 | * **and more**: 36 | Prettyprint your JSON response, make use of JSONP Callbacks, Access-Control headers, and much more. 37 | 38 | [Sign up for the Free Plan](https://vatlayer.com/product) to get your API Access Key. 39 | 40 | ## In-depth Documentation 41 | 42 | Find a shortened version of the API's Documentation in this Repository's [docs folder](https://github.com/apilayer/vatlayer-API/tree/master/docs). 43 | 44 | Interactive example queries, a variety of code examples (including PHP/CURL and jQuery.ajax) and integration guides are available at [vatlayer.com/documentation](https://vatlayer.com/documentation). 45 | 46 | ## Customer Support 47 | Need any assistance? [Get in touch with Customer Support](mailto:support@apilayer.com?subject=[vatlayer]). 48 | 49 | ## Legal 50 | 51 | All usage of the vatlayer website, API, and services is subject to the [vatlayer Terms & Conditions](https://vatlayer.com/terms) and all annexed legal documents and agreements. 52 | -------------------------------------------------------------------------------- /docs/features.md: -------------------------------------------------------------------------------- 1 | # API Features 2 | 3 | ## VAT Number Validation 4 | 5 | Both free and paid users may perform VAT number validations and company information lookups using the API's `validate` endpoint. 6 | 7 | Simply specify the `vat_number` you would like to validate and append it to the API request URL. 8 | 9 | **Example query:** 10 | 11 | ```url 12 | http://apilayer.net/api/validate 13 | ? access_key = YOUR_ACCESS_KEY 14 | & vat_number = LU26375245 15 | ``` 16 | 17 | **Example response:** 18 | 19 | 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. 20 | 21 | ```json 22 | { 23 | "valid": true, 24 | "format_valid": true, 25 | "query": "LU26375245", 26 | "country_code": "LU", 27 | "vat_number": "26375245", 28 | "company_name": "AMAZON EUROPE CORE S.A R.L.", 29 | "company_address": "5, RUE PLAETIS L-2338 LUXEMBOURG" 30 | } 31 | ``` 32 | 33 | **API response objects:** 34 | 35 | | Object | Description | 36 | | --------------|-------------- | 37 | | `valid` | Contains `true` if the VAT number you entered could be successfully validated, `false` if not. | 38 | | `format_valid` | Contains `true` if the syntax/format of the VAT number you entered is valid, `false` if not. | 39 | | `query` | Returns the entire VAT number as per your API request. | 40 | | `country_code` | The 2-letter country code assigned to the provided VAT number. | 41 | | `vat_number` | The pure VAT number without the 2-letter country code prefix. | 42 | | `company_name` | The name of the company the VAT number you entered is assigned to. | 43 | | `company_address` | The address of the company the VAT number you entered is assigned to. | 44 | 45 | ## Get VAT Rates via Country Code 46 | 47 | Using the vatlayer API's `rate` endpoint, you may request VAT rates for a country of your choice. 48 | 49 | 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. 50 | 51 | **Example query:** 52 | 53 | ```url 54 | http://apilayer.net/api/rate 55 | ? access_key = YOUR_ACCESS_KEY 56 | & country_code = DE 57 | ``` 58 | 59 | **Example response:** 60 | 61 | 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. 62 | 63 | ```json 64 | { 65 | "success": true, 66 | "country_code": "DE", 67 | "country_name": "Germany", 68 | "standard_rate": 19, 69 | "reduced_rates": { 70 | "foodstuffs": 7, 71 | "books": 7, 72 | "medical": 7, 73 | "passenger transport": 7, 74 | "newspapers": 7, 75 | "admission to cultural events": 7, 76 | "admission to entertainment events": 7, 77 | "hotels": 7 78 | } 79 | } 80 | ``` 81 | 82 | **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`. 83 | 84 | ## Reduced VAT Rates - Types of Goods 85 | 86 | Each country declares individual types of goods that fall into reduced VAT categories, such as medical goods, hotels and books. 87 | 88 | You may access a full list containing all available reduced VAT rate types via the API's `types` endpoint. 89 | 90 | **Example query:** 91 | 92 | ```url 93 | http://apilayer.net/api/types 94 | ? access_key = YOUR_ACCESS_KEY 95 | ``` 96 | 97 | **Please note:** Requesting the API's `types` endpoint does not count against your monthly API request volume. 98 | 99 | ## Get VAT Rates via IP Address 100 | 101 | 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. 102 | 103 | **Example query:** 104 | 105 | ```url 106 | http://apilayer.net/api/rate 107 | ? access_key = YOUR_ACCESS_KEY 108 | & ip_address = 134.245.44.17 109 | ``` 110 | 111 | **Note**: In this case, the API response will be identical to the one listed in the previous example. ("Get VAT Rates via Country Code") 112 | 113 | **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`. 114 | 115 | ## Get VAT Rates via Client IP 116 | 117 | 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. 118 | 119 | 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`. 120 | 121 | **Example query:** 122 | 123 | ```url 124 | http://apilayer.net/api/rate 125 | ? access_key = YOUR_ACCESS_KEY 126 | & use_client_ip = 1 127 | ``` 128 | 129 | **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. 130 | 131 | **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. 132 | 133 | ## Retrieve all EU VAT Rates 134 | 135 | Using the vatlayer API's `rate_list` endpoint, you may also request VAT rates for all 28 EU member states at once. 136 | 137 | **Example query:** 138 | 139 | ```url 140 | http://apilayer.net/api/rate_list 141 | ? access_key = YOUR_ACCESS_KEY 142 | ``` 143 | 144 | **Important:** 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. 145 | 146 | ## VAT Compliant Price Calculation 147 | 148 | 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: 149 | 150 | **Required parameter: conversion amount** 151 | 152 | First, you'll need to specify the `amount` you would like to use for your VAT price calculation: 153 | 154 | ```bsh 155 | amount the amount/price you would like to calculate 156 | in compliance with EU VAT rates 157 | ``` 158 | 159 | **Required parameter: country** 160 | 161 | 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: 162 | 163 | ```bsh 164 | country_code define country by appending a two 2-letter 165 | country code of your choice 166 | 167 | ip_address define country by appending a custom IP 168 | address to be located by the API 169 | 170 | use_client_ip define country by having the API locate the 171 | IP address of the client making the API call 172 | ``` 173 | 174 | **Example query:** 175 | 176 | ```url 177 | http://apilayer.net/api/price 178 | ? access_key = YOUR_ACCESS_KEY 179 | & amount = 125 180 | & country_code = GB 181 | ``` 182 | 183 | **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. 184 | 185 | **Example response:** 186 | 187 | 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. 188 | 189 | ```json 190 | { 191 | "success": true, 192 | "country_code": "GB", 193 | "country_name": "United Kingdom", 194 | "price_excl_vat": 125, 195 | "price_incl_vat": 150, 196 | "vat_rate": 20 197 | } 198 | ``` 199 | 200 | ### Advanced VAT Price Calculation Options 201 | 202 | The `price` endpoint also offers two optional parameters: 203 | 204 | **Optional parameter: type of goods** 205 | 206 | 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. 207 | 208 | ```bsh 209 | type the type of goods according to the 210 | API's "types" endpoint 211 | ``` 212 | 213 | **Optional parameter: VAT already included** 214 | 215 | 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`. 216 | 217 | ```bsh 218 | incl set to 1 if amount already includes 219 | VAT percentage 220 | ``` 221 | 222 | **Example query:** 223 | 224 | ```url 225 | http://apilayer.net/api/price 226 | ? access_key = YOUR_ACCESS_KEY 227 | & amount = 125 228 | & country_code = GB 229 | & type = medical 230 | & incl = 1 231 | ``` 232 | 233 | **Example response:** 234 | 235 | In the United Kingdom there is no VAT rate applying to `medical` products, therefore the API will return a `vat_rate` of `0`. 236 | 237 | ```json 238 | { 239 | "success": true, 240 | "country_code": "GB", 241 | "country_name": "United Kingdom", 242 | "price_excl_vat": 125, 243 | "price_incl_vat": 125, 244 | "type": "medical" 245 | "vat_rate": 0 246 | } 247 | ``` 248 | 249 | 250 | 251 | -------------------------------------------------------------------------------- /docs/language-examples/jquery-ajax.md: -------------------------------------------------------------------------------- 1 | # Code Examples 2 | 3 | ## JavaScript (jQuery.ajax) - Validate VAT Number 4 | 5 | ```javascript 6 | // set endpoint and your access key 7 | var endpoint = 'validate' 8 | var access_key = 'YOUR_ACCESS_KEY'; 9 | var vat_number = 'LU26375245'; 10 | 11 | // validate VAT number via AJAX call 12 | $.ajax({ 13 | url: 'https://apilayer.net/api/' + endpoint + '?access_key=' + access_key + '&vat_number=' + vat_number, 14 | dataType: 'jsonp', 15 | success: function(json) { 16 | 17 | // Access and use your preferred validation result objects 18 | alert(json.valid); 19 | alert(json.query); 20 | alert(json.company_name); 21 | alert(json.company_address); 22 | 23 | } 24 | }); 25 | ``` 26 | 27 | **Please note:** In this example, the use of JSONP is entirely optional. 28 | -------------------------------------------------------------------------------- /docs/language-examples/php-curl.md: -------------------------------------------------------------------------------- 1 | # Code Examples 2 | 3 | ## PHP (cURL): Validate VAT Number: 4 | 5 | ```php 6 | // set API Endpoint and Access Key 7 | $endpoint = 'validate'; 8 | $access_key = 'YOUR_ACCESS_KEY'; 9 | 10 | // set VAT number 11 | $vat_number = 'LU26375245'; 12 | 13 | // Initialize CURL: 14 | $ch = curl_init('http://apilayer.net/api/'.$endpoint.'?access_key='.$access_key.'&vat_number='.$vat_number.''); 15 | curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); 16 | 17 | // Store the data: 18 | $json = curl_exec($ch); 19 | curl_close($ch); 20 | 21 | // Decode JSON response: 22 | $validationResult = json_decode($json, true); 23 | 24 | // Access and use your preferred validation result objects 25 | $validationResult['valid']; 26 | $validationResult['query']; 27 | $validationResult['company_name']; 28 | $validationResult['company_address']; 29 | ``` 30 | 31 | -------------------------------------------------------------------------------- /docs/specifications.md: -------------------------------------------------------------------------------- 1 | # Specifications & Overview 2 | 3 | ## API Access Key & Authentication 4 | 5 | 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. 6 | 7 | To authenticate with the vatlayer API, simply attach your `access_key` to your preferred Endpoint URL: 8 | 9 | ```url 10 | http://apilayer.net/api/validate?access_key=YOUR_ACCESS_KEY 11 | ``` 12 | 13 | You can [sign up for a free Access Key here](https://vatlayer.com/product). 14 | 15 | ## API Response 16 | 17 | 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. 18 | 19 | ```json 20 | { 21 | "valid": true, 22 | "format_valid": true, 23 | "query": "LU26375245", 24 | "country_code": "LU", 25 | "vat_number": "26375245", 26 | "company_name": "AMAZON EUROPE CORE S.A R.L.", 27 | "company_address": "5, RUE PLAETIS L-2338 LUXEMBOURG" 28 | } 29 | ``` 30 | 31 | ## API Endpoints - Quick Overview 32 | 33 | The vatlayer API offers 4 main data endpoints, all of which providing different kinds of services and starting out with the following Base URL: 34 | 35 | ```url 36 | http://apilayer.net/api/ 37 | ``` 38 | 39 | Take a look at the following two API Endpoints: 40 | 41 | **Endpoint 1: Simple VAT number validation** 42 | 43 | `validate` endpoint 44 | 45 | ```url 46 | http://apilayer.net/api/validate 47 | ? access_key = YOUR_ACCESS_KEY 48 | & vat_number = VAT_NUMBER 49 | ``` 50 | 51 | **Endpoint 2: VAT rate for single EU member state** 52 | 53 | `rate` endpoint 54 | 55 | ```url 56 | // via country code 57 | http://apilayer.net/api/rate 58 | ? access_key = YOUR_ACCESS_KEY 59 | & country_code = GB 60 | 61 | // via custom IP address 62 | http://apilayer.net/api/rate 63 | ? access_key = YOUR_ACCESS_KEY 64 | & ip_address = 176.249.153.36 65 | 66 | // via client IP address 67 | http://apilayer.net/api/rate 68 | ? access_key = YOUR_ACCESS_KEY 69 | & use_client_ip = 1 70 | ``` 71 | 72 | **Endpoint 3: VAT rates for all EU member states** 73 | 74 | `rate_list` endpoint 75 | 76 | ```url 77 | http://apilayer.net/api/rate_list 78 | ? access_key = YOUR_ACCESS_KEY 79 | ``` 80 | 81 | **Endpoint 4: Price calculation** 82 | 83 | `price` endpoint 84 | 85 | ```url 86 | http://apilayer.net/api/price 87 | ? access_key = YOUR_ACCESS_KEY 88 | & amount = 100 89 | & country_code = GB 90 | ``` 91 | 92 | ## 256-bit HTTPS Encryption 93 | 94 | Paid Customers may establish a secure connection (industry-standard SSL) to the vatlayer API and all data provided by and accessible through it. 95 | 96 | To connect securely, simply attach an `s` to the HTTP Protocol. (resulting in `https://`) 97 | 98 | 99 | ## API Error Codes 100 | 101 | 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. 102 | 103 | Find below an example error - triggered when the user did not provide a valid API Access Key: 104 | 105 | ```json 106 | { 107 | "success": false, 108 | "error": { 109 | "code": 104, 110 | "type": "invalid_access_key", 111 | "info": "You have not supplied a valid API Access Key. [Technical Support: support@apilayer.net]" 112 | } 113 | } 114 | ``` 115 | 116 | The following list should help you find the most commonly returned API Errors: 117 | 118 | | Type | Message | Description | 119 | |------------ |---------------| -----| 120 | | 404 | "404_not_found" | User requested a resource which does not exist. | 121 | | 101 | "missing_access_key" | User did not supply an Access Key. | 122 | | 101 | "invalid_access_key" | User entered an invalid Access Key. | 123 | | 103 | "invalid_api_function" | User requested a non-existend API Function. | 124 | | 104 | "usage_limit_reached" | User has reached or exceeded his Subscription Plan's monthly API Request Allowance. | 125 | | 210 | "no_vat_number_supplied" | User did not provide a VAT Number. | 126 | 127 | [See all Error Types](https://vatlayer.com/documentation#error_codes) 128 | 129 | ## JSONP Callbacks 130 | 131 | The vatlayer API also supports **JSONP** for cross-domain/AJAX requests. To use this feature, simply append: 132 | 133 | `?callback=SOME_CALLBACK` 134 | 135 | to any valid API Endpoint, and the result set will be returned **wrapped in the specified callback function**: 136 | 137 | ```json 138 | http://apilayer.net/api/validate?callback=SOME_CALLBACK 139 | ``` 140 | 141 | **Note**: The API also supports `Access-Control (CORS)` headers. 142 | 143 | ## JSON Formatting 144 | 145 | In order to enhance readability (i.e. for de-bugging purposes), the currencylayer API features a built-in JSON `format` function, which displays the API's Response in typically JSON-structured format. 146 | 147 | To enable this function, simply append `format=1` to any valid API Endpoint URL: 148 | 149 | ``` 150 | http://apilayer.net/api/validate 151 | ? access_key = YOUR_ACCESS_KEY 152 | [...] 153 | & format = 1 154 | ``` 155 | 156 | Please be aware that enabling `format` increases the API Response's file size, which might have a negative on your application's performance. 157 | --------------------------------------------------------------------------------