VatProtect.com
Developers

API Documentation

Integrate real-time EU VAT validation into your application. Validate VAT IDs against the official VIES database via a simple REST API — confirm validity plus the registered company name and address.

This guide walks you through integrating VAT ID validation into your app — for financial software, e-commerce platforms, or anything that needs VAT verification. Explore the endpoints below to get started.

Authentication

The API endpoints require authentication using one of the following methods:

Please obtain the API key from your user account to authenticate your requests.

Test API key: test. Only works with specific VAT IDs:

Check VAT ID

GET /api/check/{$vatId}

This endpoint validates a VAT ID number.

Required Parameters
Parameter Type Description Example
vatId string VAT ID number to validate SE556313500201
Example Success Response
{
  "error": false,
  "errorMessage": "OK",
  "vatId": "SE556313500201",
  "vatIdCountryCode": "SE",
  "vatIdNumber": "556313500201",
  "vatIdValid": true,
  "companyName": "BMW Northern Europe AB",
  "companyAddress": "BOX 794 \n191 27 SOLLENTUNA",
  "date": "2023-08-01T21:31:15+02:00"
}
Example Error Response
{
  "error": true,
  "errorMessage": "Invalid test VAT ID."
}
Response Elements
  • error (boolean): Indicates if an error occurred. true if there is an error, otherwise false.
    Note: If there is an error, the other response elements, except errorMessage, will not be present.
    Note: If there is no error, the errorMessage will be "OK".
    Note: An invalid VAT ID is not considered an error. The error element will be false and the vatIdValid element will be false.
  • errorMessage (string): A descriptive message regarding the request status. For successful requests, it will be "OK".
  • vatId (string): The provided VAT ID number.
  • vatIdCountryCode (string): The country code extracted from the VAT ID (e.g., "SE" for Sweden).
  • vatIdNumber (string): The numeric part of the VAT ID (e.g., "556313500201").
  • vatIdValid (boolean): Indicates if the provided VAT ID is valid. true if valid, otherwise false.
  • companyName (string): The name of the company associated with the VAT ID.
    Note: This element can be empty or --- or similar if the company name is not available.
  • companyAddress (string): The address of the company associated with the VAT ID.
    Note: This element can be empty or --- or similar if the company address is not available.
  • date (string): The date and time of the response in ISO 8601 format (e.g., "2023-08-01T21:31:15+02:00").
Error Messages for VatProtect.com service
  • Invalid API key. - HTTP Status Code 401

    Description: The provided API key is invalid. Ensure you are using a valid API key for authentication.

  • No API key provided. - HTTP Status Code 401

    Description: No API key was provided in the request. Make sure to include the API key as either an Authorization header or a GET parameter.

  • You exceeded your current quota. Please contact support@vatprotect.com if you think this is a mistake. - HTTP Status Code 429

    Description: The request has exceeded the allowed quota for the current time period. Please contact support if you believe this is an error.

  • Invalid test VAT ID - HTTP Status Code 400

    Description: The provided VAT ID for testing purposes is not a valid VAT ID. Please use a valid VAT ID for testing.

  • Invalid user - HTTP Status Code 400

    Description: The user associated with the API key is invalid or not authorized to access the resource.

Error Messages for external data providers (such as VIES)
  • OK - HTTP Status Code 200

    Description: The request was successful, and the VAT ID is valid.

  • Invalid VAT ID format - HTTP Status Code 200

    Description: The provided VAT ID has an invalid format. Check the format and try again.

  • Service unavailable - HTTP Status Code 200

    Description: The service is temporarily unavailable. Please try again later.

  • Error - HTTP Status Code 200

    Description: An unspecified error occurred while processing the request. Please contact support if the issue persists.

Sample code

Test API key

Test API key: test. Only works with specific VAT IDs:

Request:
GET /api/check/SE556313500201?apiKey=your_api_key_here HTTP/1.1
Host: vatprotect.com
Response:
HTTP/1.1 200 OK
Content-Type: application/json

{
  "error": false,
  "errorMessage": "OK",
  "vatId": "SE556313500201",
  "vatIdCountryCode": "SE",
  "vatIdNumber": "556313500201",
  "vatIdValid": true,
  "companyName": "BMW Northern Europe AB",
  "companyAddress": "BOX 794 \n191 27 SOLLENTUNA",
  "date": "2023-08-01T21:31:15+02:00"
}

Request:
GET /api/check/SE556313500201 HTTP/1.1
Host: vatprotect.com
Authorization: Bearer your_api_key_here
Response:
HTTP/1.1 200 OK
Content-Type: application/json

{
  "error": false,
  "errorMessage": "OK",
  "vatId": "SE556313500201",
  "vatIdCountryCode": "SE",
  "vatIdNumber": "556313500201",
  "vatIdValid": true,
  "companyName": "BMW Northern Europe AB",
  "companyAddress": "BOX 794 \n191 27 SOLLENTUNA",
  "date": "2023-08-01T21:31:15+02:00"
}

Request:
curl -X GET "https://vatprotect.com/api/check/SE556313500201?apiKey=your_api_key_here"
Response:
{
  "error": false,
  "errorMessage": "OK",
  "vatId": "SE556313500201",
  "vatIdCountryCode": "SE",
  "vatIdNumber": "556313500201",
  "vatIdValid": true,
  "companyName": "BMW Northern Europe AB",
  "companyAddress": "BOX 794 \n191 27 SOLLENTUNA",
  "date": "2023-08-01T21:31:15+02:00"
}

Request:
curl -X GET "https://vatprotect.com/api/check/SE556313500201" -H "Authorization: Bearer your_api_key_here"
Response:
{
  "error": false,
  "errorMessage": "OK",
  "vatId": "SE556313500201",
  "vatIdCountryCode": "SE",
  "vatIdNumber": "556313500201",
  "vatIdValid": true,
  "companyName": "BMW Northern Europe AB",
  "companyAddress": "BOX 794 \n191 27 SOLLENTUNA",
  "date": "2023-08-01T21:31:15+02:00"
}
            

<?php
// Include Guzzle HTTP client
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$apiKey = 'your_api_key_here';
$vatId = 'SE556313500201';

$client = new Client();

// HTTP Request with Authorization Header
$headers = ['Authorization' => "Bearer {$apiKey}"];
$response = $client->get("https://vatprotect.com/api/check/{$vatId}", ['headers' => $headers]);
$data = json_decode($response->getBody(), true);

// Handle the response data as needed
// ...
?>
            

<script>
const apiKey = 'your_api_key_here';
const vatId = 'SE556313500201';

// HTTP Request with apiKey GET Parameter
axios.get(`https://vatprotect.com/api/check/${vatId}?apiKey=${apiKey}`)
  .then(response => {
    const data = response.data;
    // Handle the response data as needed
    // ...
  })
  .catch(error => {
    // Handle error responses
    console.error(error);
  });
</script>
            

<script>
const apiKey = 'your_api_key_here';
const vatId = 'SE556313500201';

// HTTP Request with Authorization Header
const headers = { Authorization: `Bearer ${apiKey}` };
axios.get(`https://vatprotect.com/api/check/${vatId}`, { headers })
  .then(response => {
    const data = response.data;
    // Handle the response data as needed
    // ...
  })
  .catch(error => {
    // Handle error responses
    console.error(error);
  });
</script>
            

import requests

apiKey = 'your_api_key_here'
vatId = 'SE556313500201'

# HTTP Request with apiKey GET Parameter
url = f'https://vatprotect.com/api/check/{vatId}?apiKey={apiKey}'
response = requests.get(url)
data = response.json()

# Handle the response data as needed
# ...
            

import requests

apiKey = 'your_api_key_here'
vatId = 'SE556313500201'

# HTTP Request with Authorization Header
headers = {'Authorization': f'Bearer {apiKey}'}
url = f'https://vatprotect.com/api/check/{vatId}'
response = requests.get(url, headers=headers)
data = response.json()

# Handle the response data as needed
# ...