API Features
VAT Number Validation
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:
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.
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 carried out.
To properly reflect whether or not the requested VAT number can be matched with the responsible 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.
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.
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
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 parameters that can be used to define the country to obtain VAT rates for. In this example, we'll determine the country by appending the simple 2-letter country_code parameter to the request URL.
Example query:
Example response:
Along with a success indication and country information, the API's JSON response will include a standard_rate field 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.
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 complete list containing all available reduced VAT rate types via the API's types endpoint.
Example query:
Please note: Requesting the API's types endpoint does not count against your monthly API request volume.
Get VAT Rates via IP Address
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:
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
In addition to EU VAT rates via the country_code and ip_address parameters, you may also request the API to determine the country using the client's IP address at the time of the API call.
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:
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
Using the VATlayer API's rate_list endpoint, you may also request VAT rates for all 28 EU member states at once.
Example query:
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
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:
Required parameter: country
As mentioned above, there are three parameters that can be used to define the country for which VAT rates are to be obtained. Choose only one of the following:
Example query:
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 returning 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 containing the EU VAT rate used for your price calculation.
Advanced VAT Price Calculation Options
The price endpoint also offers two optional parameters:
Optional parameter: type of goods
If your product falls under the "reduced VAT rates" category, you may specify the type of goods using the API's types endpoint (Learn more).
Optional parameter: VAT already included
If you are supplying an amount that already includes the applicable VAT percentage and would like the API to perform a reverse calculation, simply set the API's incl parameter to 1.
Example query:
Example response:
In the United Kingdom, no VAT rate applies to medical products; therefore, the API will return a vat_rate of 0.