API Documentation

The EUVATAPI API is a JSON REST API which provides EU VAT number validation, EU VAT rates based on IP address, country code or user geolocation and calculated prices including EU VAT.

API requests are made using a friendly URL structure and results are returned in JSON format, providing a simple integration and full compatibility with any application, programming language or framework.

This API documentation explains all the parameters and features with integration examples and code examples for PHP and Curl. 

                        
                        https://euvatapi.com/api/v1/

Authentication

After signing up, you will receive an API access key to access any of the API endpoints.

To authenticate with the API, you must provide your API access key in the access_key parameter of the API endpoint URL: 

                                    
                                   curl --url 'https://euvatapi.com/api/v1/validate?access_key=YOUR_ACCESS_KEY&vat_number=LU26375245'
                                
                        
                                    <?php
// configure request
$endpoint = 'https://euvatapi.com/api/v1/validate?access_key=YOUR_ACCESS_KEY'&vat_number=LU26375245sensors;

// init curl
$ch = curl_init();

// set curl options
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);

curl_close($ch);

// print response as json
header('Content-Type: application/json');

// print response
print_r($response);

Responses

All API data is returned in an easily parsable JSON format.

Below is an example response using the validate endpoint to validate a VAT number.

{
  "success": true,
  "valid": true,
  "format_valid": true,
  "database": "ok",
  "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"
}

Errors

If your request fails, the API will return a 3-digit error-code along with an internal error type and a plain text "info" parameter containing suggestions for the user.

Below is an example error caused by providing an invalid API Access Key. 

{
  "success": false,
  "error": {
    "code": 102,
    "type": "invalid_access_key",
    "info": "You supplied an invalid Access Key."
  }
}

API error codes:

Code Type Description
101 missing_access_key You did not supply an Access Key.
102 invalid_access_key You supplied an invalid Access Key.
104 usage_limit_reached You have reached your subscription plan's monthly API request allowance.
106 invalid_callback_function_name You have not supplied a valid callback function name.
210 no_vat_number_supplied You did not provide a VAT Number.
310 no_country_code_or_ip_supplied You did not provide a Country Code or IP Address.
311 both_country_code_and_ip_supplied You provided both Country Code and IP Address. Only one of the two can be used.
410 invalid_ip_address You have provided an invalid IP Address.
411 could_not_resolve_ip The IP Address you specified could not be resolved. Please try again or contact support.
404 404_not_found The requested API resource does not exist.
405 method_not_allowed Method not allowed. Supported methods: GET, POST.
510 invalid_country_code You have specified an invalid Country Code.
609 missing_amount_key You have not provided an amount value.
610 invalid_amount You provided an invalid amount value.
500 server_error Something went wrong - Internal server error.

Please Note: This is not a complete list of errors. If you come receive an error message you are not sure about please contact our support.

JSONP Callbacks

The API also supports JSONP callbacks so you can use the service in javascript.

To specify the javascript function to be called, provide the callback= parameter to any of the endpoints.

Not sure what JSONP is? Here's an explanation Stack Overflow. 

                        

// Set the endpoint and the callback function name
var endpoint = 'https://euvatapi.com/api/v1/validate?vat_number=LU26375245&access_key=YOUR_ACCESS_KEY&callback=my_callback_function';

// Define the callback function
function my_callback_function(json){
    //log to the console
    console.log('json', json);
    // Alert the result object properties
    alert(json.valid);
    alert(json.query);
    alert(json.company_name);
    alert(json.company_address);
}

// Validate VAT number via jQuery AJAX call with JSONP callback
$.ajax(
    url: endpoint,
    dataType: 'jsonp',
    jsonpCallback: 'my_callback_function',
    jsonp: 'callback',
});

                    
                                        my_callback_function({
  {
    "valid": true,
    "format_valid": true,
    "database": "ok",
    "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"
  }
})

VAT Number Validation

You can 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.

Response Attributes

success

boolean

Contains true if the request was processed successfully and did not generate any errors and false if there was a problem.

valid

boolean

Contains true if the VAT number you provided could be successfully validated, false if not.

format_valid

boolean

Contains true if the syntax/format of the VAT number you provided is valid, false if not.

database

string

Contains ok if the EU member state's VAT database is currently able to process the VAT number validation, failure if not.

query

string

Returns the VAT number provided.

country_code

string

The 2-letter country code used to validate the VAT number.

vat_number

string

The VAT number without the 2-letter country code prefix (if provided).

company_name

string

The name of the company the VAT number is assigned to (if available).

company_address

string

The address of the company the VAT number is assigned to (if available). 

                                    
                                   curl --url 'https://euvatapi.com/api/v1/validate?access_key=YOUR_ACCESS_KEY&vat_number=LU26375245'
                                
                        
                                    <?php
// configure request
$endpoint = 'https://euvatapi.com/api/v1/validate?access_key=YOUR_ACCESS_KEY&vat_number=LU26375245';

// init curl
$ch = curl_init();

// set curl options
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);

curl_close($ch);

// print response as json
header('Content-Type: application/json');

// print response
print_r($response);
                                
                                        {
  "valid": true,
  "format_valid": true,
  "database": "ok",
  "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"
}

VAT Database Status

Since each EU Member State is required to keep its VAT number database information current and correct, regular database updates (which can result in temporary downtime of the respective member state's database) are performed.

To ensure that the requested VAT number can be matched in the relevant member state's database when the API request is made, the API returns an additional database JSON property containing "ok" if the required database is available, and "failure", if not.

Handling "database": "failure"

If a connection to the member state's database could not be established and therefore the database property returns "failure", the API's valid object will automatically return false.

Important: To ensure the correctness of VAT number validation results, check your database connection even before taking any actions based on the validation result that is contained in the response's valid property. 
                                        {
  [...]
  "valid": false,
  "database": "ok",
  [...]
}
valid false and database "ok" - The VAT number is not valid 
                                        {
  "valid": false,
  "database": "failure",
  [...]
}
valid false and database "failure" - The validation must be retried later as the VAT number has not been checked

Get VAT Rates via Country Code

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

Please note: There are 3 different parameters that can be used to identify the country required to obtain VAT rates for. In this example, we will provide the 2-letter country_code parameter to the request URL.
Please note: If you provide a country code outside of the EU, the API will not return an error, it will return a VAT rate of 0.
Response Attributes

success

boolean

Whether the call has resulted in a successful response.

country_code

string

The 2-letter country code.

country_name

string

Contains the full country name.

standard_rate

float

Contains percentage standard VAT rate used by the country code.

other_rates

object

Contains an array of "other rate" objects and/or empty array if the country has only a standard rate.

Other Rate Object Attributes

rate

float

Contains percentage VAT rate used for the described products or services.

class

string

The class of the VAT rate. This can be "reduced", "higher", "exempt" or "zero".

description

string

Contains a text description to clarify which products or services the rate is applied to. 

                                    
                                   curl --url 'https://euvatapi.com/api/v1/rate?access_key=YOUR_ACCESS_KEY&country_code=DE'
                                
                        
                                    <?php
// configure request
$endpoint = 'https://euvatapi.com/api/v1/rate?access_key=YOUR_ACCESS_KEY&country_code=DE';

// init curl
$ch = curl_init();

// set curl options
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);

curl_close($ch);

// print response as json
header('Content-Type: application/json');

// print response
print_r($response);
                                
                                        {
  "success": true,
  "country_code": "DE",
  "country_name": "Germany",
  "standard_rate": 19,
  "other_rates": [
     {
        "rate": 7,
        "class": "reduced",
        "description": "Some foodstuffs; water supplies (excluding bottled water); medical equipment for disabled persons; some domestic passenger transport; intra-community and international passenger transport for certain road, rail and inland waterway transportation; books (excluding books whose content is harmful to minors); e-books; audiobooks; newspapers and periodicals (except those containing content harmful to minors and\/or more than 50% advertising); admission to cultural events; writers and composers; some agricultural inputs; hotel accommodation (only short-term accommodation); certain admission to sports events; social services; medical and dental care; firewood; some timber for industrial use; take away food; cut flowers and plants for decorative use and food production; taxation of some gold coins and jewellery",
     },
     ...
  ]
}

Get VAT Rates via IP Address

To identify the relevant country by geolocating an IP address simply append the ip_address query parameter.

Please note: The API response is identical to the one listed in the previous example. (Get VAT Rates via Country Code)
Please note: If you provide an IP address outside of the European Union, the API will not return an error. Instead, it will return a VAT rate of 0. 
                                    
                                   curl --url 'https://euvatapi.com/api/v1/rate?access_key=YOUR_ACCESS_KEY&ip_address=2.16.101.255'
                                
                        
                                    <?php
// configure request
$endpoint = 'https://euvatapi.com/api/v1/rate?access_key=YOUR_ACCESS_KEY&ip_address=2.16.101.255';

// init curl
$ch = curl_init();

// set curl options
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);

curl_close($ch);

// print response as json
header('Content-Type: application/json');

// print response
print_r($response);
                                
                                        {
  "success": true,
  "country_code": "DE",
  "country_name": "Germany",
  "standard_rate": 19,
  "other_rates": [
     {
        "rate": 7,
        "class": "reduced",
        "description": "Some foodstuffs; water supplies (excluding bottled water); medical equipment for disabled persons; some domestic passenger transport; intra-community and international passenger transport for certain road, rail and inland waterway transportation; books (excluding books whose content is harmful to minors); e-books; audiobooks; newspapers and periodicals (except those containing content harmful to minors and\/or more than 50% advertising); admission to cultural events; writers and composers; some agricultural inputs; hotel accommodation (only short-term accommodation); certain admission to sports events; social services; medical and dental care; firewood; some timber for industrial use; take away food; cut flowers and plants for decorative use and food production; taxation of some gold coins and jewellery",
     },
     ...
  ]
}

Get VAT Rates via Client IP

Additionally to EU VAT rates via the country_code and ip_address parameters, you may also request the API to identify the country by geolocating the IP address making the request.

To have the API use the client's IP address to identify the county required, simply set the requests use_client_ip parameter to 1.

Please note: Getting the VAT rate by client IP is only relevant if you are accessing the API via javascript in the client browser. If you are requesting from your server then the request IP will always be from the server. 
                        

// Set the endpoint and use_client_ip = 1
var endpoint = 'https://euvatapi.com/api/v1/rate?access_key=YOUR_ACCESS_KEY&use_client_ip=1';

// get the VAT rates via jQuery AJAX
$.get(endpoint,  function(result){
    // log to the console
    console.log('result', result);
    // Alert the validation result object properties
    alert(json.country_code);
    alert(json.country_name);
    alert(json.standard_rate);
});

                    
                                        {
  "success": true,
  "country_code": "DE",
  "country_name": "Germany",
  "standard_rate": 19,
  "other_rates": [
     {
        "rate": 7,
        "class": "reduced",
        "description": "Some foodstuffs; water supplies (excluding bottled water); medical equipment for disabled persons; some domestic passenger transport; intra-community and international passenger transport for certain road, rail and inland waterway transportation; books (excluding books whose content is harmful to minors); e-books; audiobooks; newspapers and periodicals (except those containing content harmful to minors and\/or more than 50% advertising); admission to cultural events; writers and composers; some agricultural inputs; hotel accommodation (only short-term accommodation); certain admission to sports events; social services; medical and dental care; firewood; some timber for industrial use; take away food; cut flowers and plants for decorative use and food production; taxation of some gold coins and jewellery",
     },
     ...
  ]
}

Retrieve all EU VAT Rates

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

Please note: The VAT rate response objects for each country are identical to the one listed in the previous single rates example. (Get VAT Rates via Country Code) 
                                    
                                   curl --url 'https://euvatapi.com/api/v1/rate_list?access_key=YOUR_ACCESS_KEY'
                                
                        
                                    <?php
// configure request
$endpoint = 'https://euvatapi.com/api/v1/rate_list?access_key=YOUR_ACCESS_KEY';

// init curl
$ch = curl_init();

// set curl options
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);

curl_close($ch);

// print response as json
header('Content-Type: application/json');

// print response
print_r($response);
                                
                                        {
  "success": true,
  "rates": {
      "DE": {
          "country_code": "DE",
          "country_name": "Germany",
          "standard_rate": 19,
          "other_rates": [
             {
                "rate": 7,
                "class": "reduced",
                "description": "Some foodstuffs; water supplies (excluding bottled water); medical equipment for disabled persons; some domestic passenger transport; intra-community and international passenger transport for certain road, rail and inland waterway transportation; books (excluding books whose content is harmful to minors); e-books; audiobooks; newspapers and periodicals (except those containing content harmful to minors and\/or more than 50% advertising); admission to cultural events; writers and composers; some agricultural inputs; hotel accommodation (only short-term accommodation); certain admission to sports events; social services; medical and dental care; firewood; some timber for industrial use; take away food; cut flowers and plants for decorative use and food production; taxation of some gold coins and jewellery",
             },
            ...
        ]
      },
      ...
  }
}

VAT Compliant Price Calculation

Using the API's price endpoint, you may request the API to calculate VAT compliant prices using the countries standard rate. This API endpoint requires two query parameters which are explained below:

Required parameter: conversion amount

You need to specify the amount you would like to use for your VAT price calculation as an integer:

Required parameter: country

As already mentioned above, three different parameters can be used to identify the country and obtain the required VAT rates. Choose only one of the following:

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

                                    
                                   curl --url 'https://euvatapi.com/api/v1/price?access_key=YOUR_ACCESS_KEY&amount=100&country_code=DE'
                                
                        
                                    <?php
// configure request
$endpoint = 'https://euvatapi.com/api/v1/price?access_key=YOUR_ACCESS_KEY&amount=100&country_code=DE';

// init curl
$ch = curl_init();

// set curl options
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);

curl_close($ch);

// print response as json
header('Content-Type: application/json');

// print response
print_r($response);
                                
                                        {
  "success": true,
  "country_code": "DE",
  "country_name": "Germany",
  "price_excl_vat": 100,
  "price_incl_vat": 119,
  "vat_rate": 19
}