API Documentation

Welcome to our VAT Validation Service API documentation.

This comprehensive guide will walk you through the simple and efficient process of integrating VAT ID validation into your applications. With our API, you can easily validate VAT IDs and perform hassle-free checks.

Whether you're developing a financial app, e-commerce platform, or any application that requires VAT verification, our service streamlines the process, saving you time and resources.

Explore our user-friendly endpoints and detailed guides to get started with seamless VAT ID validation today. Enjoy the reliability and accuracy of our service and enhance your applications effortlessly.

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
# ...