Getting Started
API Access Key & Authentication
After signing up, every user is assigned a personal API Access Key—a unique "password" that provides access to any of the API's data endpoints (see API Endpoints).
To authenticate with the VATlayer API, simply attach your access_key to your preferred Endpoint URL:
Get free API Access Key
API Response
All VATlayer API data is returned in easily parseable JSON format. Find below an example API response using the validate endpoint to validate a VAT number.
The response properties for each API endpoint are explained in the API Features section.
API Endpoints - Quick Overview
The VATlayer API offers 4 main data endpoints, all of which provide different kinds of services, and starting out with the following Base URL:
Take a look at the following two API Endpoints: (If you would like to try them out, get a Free Plan and don't forget to attach your Access Key to the URL)
Endpoint 1: Simple VAT number validation
Endpoint 2: VAT rate for a single EU member state
Endpoint 3: VAT rates for all EU member states
Endpoint 4: Price calculation
Each API Endpoint is explained in detail in the API Features section below.
256-bit HTTPS Encryption
All Customers may establish a secure connection (using industry-standard SSL) to the VATlayer API and to all data provided by and accessible through it. To connect securely, simply attach an s to the HTTP Protocol. (resulting in https://)
API Error Codes
If your query fails, the screenshotlayer API will return a 3-digit error code, an internal error type, and a plain text "info" object containing suggestions for the user.
Find below an example error - triggered when the user did not provide a valid API Access Key:
Common API errors:
| Type | Message | Description |
|---|---|---|
| 404 | "404_not_found" | User requested a resource which does not exist. |
| 101 | "missing_access_key" | User did not supply an Access Key. |
| 101 | "invalid_access_key" | User entered an invalid Access Key. |
| 103 | "invalid_api_function" | User requested a non-existent API Function. |
| 104 | "usage_limit_reached" | User has reached or exceeded his Subscription Plan's monthly API Request Allowance. |
| 210 | "no_vat_number_supplied" | User did not provide a VAT Number. |
| 102 | "inactive_user" | The user's account is not active. User will be prompted to get in touch with Customer Support. |
| 310 | "no_country_code_or_ip_supplied" | User did not provide a Country Code or IP Address. |
| 311 | "both_country_code_and_ip_supplied" | User provided both Country Code and IP Address. Only one of the two can be processed. |
| 410 | "invalid_ip_address" | User provided an invalid IP Address. [Example: 213.162.68.117] |
| 411 | "could_not_resolve_ip" | Our system failed allocating the supplied IP Address. |
| 510 | "invalid_country_code" | User provided an invalid Country Code. (Required format: 2-letter Code - Example: GB) |
| 610 | "invalid_amount" | User provided an invalid "amount" value. (Required format: integer - Example: 10) |
| 611 | "invalid_type" | User provided an invalid "type" value. See Types of Goods. (Example: medical) |
JSONP Callbacks
The VATlayer API also supports JSONP Callbacks. To use this feature, simply attach:
to any API Endpoint, and the result set will be returned as the callback function you specified.
Example query:
Not sure about what JSONP does? Here's a helpful Stack Overflow thread.
Example response:
Note: The API also supports Access-Control (CORS) headers.
JSON Formatting
To enhance readability, the VATlayer API includes a built-in JSON formatter that displays the API's Response in a typical JSON format.
To enable this function, simply attach format=1 to any valid API Endpoint URL:
Please be aware that enabling format increases the API Response's file size, which might have a negative impact on your application's performance.