Documentation.

Introduction.

A suite of VAT APIs which let you validate VAT numbers with official government services, look up VAT rates by ISO country code and calculate price quotes compliant with official VAT rules.

The Vatfy API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

API Specifications.

Unique API Keys.

A unique API key is assigned to you during registration. It is your gateway to interact with Vatfy's API endpoints. Use your key to authenticate all your requests using the documented authentication method.

Currently, the API key cannot be re-rolled. In the event that your key has been compromised, please contact hello@vatfy.com and we will issue you a new API key. Please bear in mind that resetting your API keys will break your application, if your keys are not updated as well.

Sample API Response.

All results are returned in industry-standard JSON format which can be easily read by your application. Here is a sample response from the validation POST endpoint:

{
    "vatfyid": "db44eacd96681d409d051",
    "vat_valid": true,
    "identifier": "WAPIAAAAXyJGjt3B",
    "vat": {
        "id": "IE3206488LH",
        "number": "3206488LH",
        "country": "Ireland",
        "country_code": "IE",
        "requester": {
            "country": "Germany",
            "country_code": "DE"
        },
        "country_mismatch": true
    },
    "company": {
        "name": "STRIP*************************",
        "address": "ONE*************, NOR************, DUB*****",
        "country": "Ireland"
    },
    "timestamp": 1634387337,
    "date": "2021-10-16",
    "execution": "4.51048ms"
}

Getting started.

Implement requests within minutes using the code samples for various programming environments outlined below.

Note that the API key in each code block must be replaced with the unique public key found in your dashboard. You can find more details in the authentication reference.

To obtain results, send a POST request to our API endpoint.

cURL.
curl https://api.vatfy.com \
-d vatid_to=VAT_ID_NUMBER -d action=REQUEST_TYPE -d apikey=YOUR_API_KEY
PHP (cURL).

The best practice to perform API requests with PHP is with its built-in cURL.

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.vatfy.com");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array(
    'vatid_to' => 'VAT_ID_NUMBER',
    'action' => 'REQUEST_TYPE',
    'apikey' => 'YOUR_API_KEY'
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$json = curl_exec($ch);
curl_close ($ch);

$data = json_decode($json, true);
jQuery.

You have to link jQuery either from a CDN or a self-hosted source.

$.ajax({
    url: 'https://api.vatfy.com',
    type: 'post',
    data: {
        vatid_to: VAT_ID_NUMBER,
        action: REQUEST_TYPE,
        apikey: YOUR_API_KEY
    },
    dataType: 'json',
    success: function(result) {
        // Do something with result.data.
        console.log(result.data)
    },
    error: function(err) {
        // Handle the error.
        console.error(err.responseJSON)
    }
})

Authentication.

The Vatfy API requires an API key to authenticate requests. All requests to any of the endpoints will fail without a valid authentication.

You can view your unique API key in your account settings. You can authenticate requests using the API Key.

API Key in Query Parameters.

Add your API Key to every request by including the key in the POST query params.

Validations.

Validating VAT ID numbers only require the following parameters: vatid_to, action, apikey.

Additionally, you may specify the parameter vatid_from to set a different requester VAT ID if it differs from your account VAT ID set up in your Vatfy account settings.

cURL.
curl https://api.vatfy.com \
-d vatid_to=VAT_ID_NUMBER -d action=validate -d apikey=YOUR_API_KEY
PHP (cURL).

The best practice to perform API requests with PHP is with its built-in cURL.

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.vatfy.com");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array(
    'vatid_to' => 'VAT_ID_NUMBER',
    'action' => 'validate',
    'apikey' => 'YOUR_API_KEY'
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$json = curl_exec($ch);
curl_close ($ch);

$data = json_decode($json, true);
jQuery.

You have to link jQuery either from a CDN or a self-hosted source.

$.ajax({
    url: 'https://api.vatfy.com',
    type: 'post',
    data: {
        vatid_to: VAT_ID_NUMBER,
        action: validate,
        apikey: YOUR_API_KEY
    },
    dataType: 'json',
    success: function(result) {
        // Do something with result.data.
        console.log(result.data)
    },
    error: function(err) {
        // Handle the error.
        console.error(err.responseJSON)
    }
})

Calculations.

Calculating correct VAT prices only require the following parameters: vatid_to, action, apikey, pricevalue, pricecalc.

Additionally, you may specify the parameter postalcode (some postal codes in Europe have different VAT requirements than their host countries) and vatid_from to set a different requester VAT ID if it differs from your account VAT ID set up in your Vatfy account settings. Please note, that VAT calculation is dependent on the requesting as well as the receiving VAT number. Tax rates differ based on from what country to what country a price is calculated.

cURL.
curl https://api.vatfy.com \
-d vatid_to=VAT_ID_NUMBER -d action=calculate -d pricevalue=PRICE_IN_CENTS -d pricecalc=NET_OR_GROSS -d apikey=YOUR_API_KEY
PHP (cURL).

The best practice to perform API requests with PHP is with its built-in cURL.

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.vatfy.com");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array(
    'vatid_to' => 'VAT_ID_NUMBER',
    'action' => 'calculate',
    'pricevalue' => 'PRICE_IN_CENTS',
    'pricecalc' => 'NET_OR_GROSS',
    'apikey' => 'YOUR_API_KEY'
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$json = curl_exec($ch);
curl_close ($ch);

$data = json_decode($json, true);
jQuery.

You have to link jQuery either from a CDN or a self-hosted source.

$.ajax({
    url: 'https://api.vatfy.com',
    type: 'post',
    data: {
        vatid_to: VAT_ID_NUMBER,
        action: calculate,
        pricevalue: PRICE_IN_CENTS,
        pricecalc: NET_OR_GROSS,
        apikey: YOUR_API_KEY
    },
    dataType: 'json',
    success: function(result) {
        // Do something with result.data.
        console.log(result.data)
    },
    error: function(err) {
        // Handle the error.
        console.error(err.responseJSON)
    }
})

Rates.

Checking correct VAT rates only require the following parameters: vatid_to, action, apikey.

cURL.
curl https://api.vatfy.com \
-d vatid_to=VAT_ID_NUMBER -d action=rate -d apikey=YOUR_API_KEY
PHP (cURL).

The best practice to perform API requests with PHP is with its built-in cURL.

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.vatfy.com");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array(
    'vatid_to' => 'VAT_ID_NUMBER',
    'action' => 'rate',
    'apikey' => 'YOUR_API_KEY'
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$json = curl_exec($ch);
curl_close ($ch);

$data = json_decode($json, true);
jQuery.

You have to link jQuery either from a CDN or a self-hosted source.

$.ajax({
    url: 'https://api.vatfy.com',
    type: 'post',
    data: {
        vatid_to: VAT_ID_NUMBER,
        action: rate,
        apikey: YOUR_API_KEY
    },
    dataType: 'json',
    success: function(result) {
        // Do something with result.data.
        console.log(result.data)
    },
    error: function(err) {
        // Handle the error.
        console.error(err.responseJSON)
    }
})

Evidence.

As a registered business within the European Union, you must collect two pieces of customer location evidence to comply with the European Union's tax laws.

Your customer’s location determines the tax rate that you need to apply to your goods and services. If you don’t calculate and collect the right amount of tax from the buyer, ou are responsible for paying the difference.

So, you must collect two pieces1 of evidence that confirm the location. This evidence could be:

  • The billing address
  • Location of the customer’s bank
  • Country which issued the credit card
  • The IP address location of the customer’s device
  • Country of the SIM card (in cases where the purchase was made on a mobile device)

1 If you are an EU business that sells below 100.000 € in cross-border sales of digital goods per year, throughout the European Union, you only need to collect one piece of customer location evidence. But it must be a piece of evidence gathered from a third party, such as the bank or IP address, and not from the customer directly.

Vatfy keeps validations, calculations and rate requests for your account for a set period of time, based on your Vatfy subscription plan. Keep this evidence on file for 10 years! These records prove that you are tax compliant, in case you have an audit. The evidence is split into multiple data points:

vatfyid

The vatfyid is our internal request identification number.

vat_valid

The vat_valid (boolean; true/false) indicates if the supplied VAT ID number passed validation and is a valid and registered business in the European Union.

identifier

The identifier is the EU VIES database evidence number. This is proof, that the requested information was delivered and processed by the European Unions databases.

vat

The vat block holds multiple data points for evidence. country and country_code shows the geographic region of the VAT ID being validated, requester with country and country_code shows the GeoIP location of the requester and returns country_mismatch (boolean; true/false) comparing the requester location with the VAT ID's geographic location.

timestamp, date

timestamp and date show the date and the timestamp of when the request was made on your side.

How to calculate Value Added Tax as an EU SaaS business

If you are a European SaaS business, you always charge VAT in your home country. You must charge VAT on every sale of digital goods. Selling outside of your home country, that's where there are differences in B2B and B2C sales.

Selling B2B in the European Union

Here you do not need to charge VAT. With the reverse-charge mechanism in place, your buyer pays VAT to their own government, but to take advantage of that, you just need to receive a valid VAT ID number from your buyer.

Selling B2C in the European Union

As a European SaaS selling to consumers (not businesses), you will effectively charge VAT, but the VAT rate you charge depends on how much you are selling in total within the European Union. Below 10.000 € in cross-border sales of digital goods per year, you are not required to register for VAT MOSS. After registering for VAT MOSS, you can charge the VAT rate of your home country on all cross-border sales.

Parameters

apikey

The Vatfy API requires an API key to authenticate requests. All requests to any of the endpoints will fail without a valid authentication. You can view your unique API key in your account settings. Add your API key to every request by including the key in the POST query params.

The API key is a 32-bit hash string.

action

action sets the operating mode of the request. These can be validate, calculate or rate.

vatid_to

vatid_to is a VAT ID number issued to businesses by their local authorities and points to the business you want to sell to or verify its VAT ID number of. This value needs to be passed without spaces.

DE 0123456789 should be passed as DE0123456789. VAT ID's with spaces will fail verification.

vatid_from

vatid_from is a VAT ID number issued to businesses by their local authorities and points to your own registered business. This value needs to be passed without spaces.

DE 0123456789 should be passed as DE0123456789. VAT ID's with spaces will fail verification.

pricevalue

pricevalue presents a full number without decimals in the smalles denominator in any currency.

A value of 100 € should be passed as 10000 (Euro Cents). Depending on pricecalc mode, the amounts to gross, net and its rounded prices will be returned.

pricecalc

pricecalc uses two operation modes: net and gross.

postalcode

Some postal codes in Europe have different Value Added Tax requirements than their host countries. Passing this optional with your request value will take these edge cases in consideration.