Validations

Validate your business customer’s VAT ID number against official government servers in real-time. The API asynchronously validates VAT ID numbers for you if government services experience downtime.

This API endpoint validates VAT ID numbers intelligently despite government service downtimes and ensures compliant record-keeping for your tax office:

  1. Every eu_vat response includes a consultation number given by VIES. The consultation number is a unique reference identifier and is an official piece of evidence used to show to tax administrations of a member state that you have rightfully validated a given VAT number on a given date.

  2. Record-keeping can be especially useful for tax-filing purposes and if you are faced with an audit. It can also be a handy fallback for repeated charges with the same customers in the event that government services are temporarily unavailable.

  3. Government service downtimes happen regularly but will be a less blocking issue from now on. Validation requests are accepted and enter a schedule for automated re-validation.

  4. Vatstack proactively notifies your server as soon as a validation request was successfully processed and a result obtained from official government servers. This means that you don’t have to query our API anymore and can instead listen to webhook events.

To help you better understand how Vatstack’s endpoint stands out against other proxied solutions, read more about how you can make best use of this endpoint.

The Validation Object

Key

Description

id

Unique identifier for the object.

code

In the event of an error, this field will contain the error code. See the list of error codes and their explanation.

company_address

Address of the company the VAT number is associated with. Servers of Germany and Spain won’t return a value for privacy reasons and will default to null.

company_name

Name of the company the VAT number is associated with. Servers of Germany and Spain won’t return a value for privacy reasons and will default to null.

consultation_number

If you save your own VAT number in your dashboard, the reply will contain a unique consultation number. The consultation number enables you to prove to a tax administration of a member state that you have checked a VAT number at the requested date, and obtained a validation result.

country_code

2-letter ISO country code. Note that while Greek VAT IDs contain the EL country code, our response will return the ISO country code GR.

created

ISO date at which the object was created.

query

Your original query.

requested

ISO date at which the validation request was originally performed. This is the request date returned by VIES and does not specify a time.

type

Type of VAT. One of eu_vat , ch_vat or no_vat.

updated

ISO date at which the object was updated.

valid

Boolean indicating whether the VAT number exists officially. If government services are down, the value will be null and re-checked automatically for you.

valid_format

Boolean indicating whether the VAT number contained in query is in a valid format.

vat_number

VAT number extracted from your query without the country code.

post
Create a validation

https://api.vatstack.com/v1/validations
Creates a validation object.
Request
Response
Request
Body Parameters
type
optional
string
Restrict validation to either ch_vat , eu_vat or no_vat. If not provided, the type is automatically determined based on the VAT ID given.
vat_id
required
string
VAT identification that you want to validate.
Response
201: Created
Validation object successfully created.
{
"id": "5d1ded3128ca7a842aaf5ed4",
"company_address": "3RD FLOOR, GORDON HOUSE, BARROW STREET, DUBLIN 4",
"company_name": "GOOGLE IRELAND LIMITED",
"consultation_number": "WAPIAAAAW21qsOHW",
"country_code": "IE",
"query": "IE6388047V",
"type": "eu_vat",
"valid": true,
"valid_format": true,
"vat_number": "6388047V",
"requested": "2019-07-04T00:00:00.000Z",
"created": "2019-07-04T12:12:33.322Z",
"updated": "2019-07-04T12:12:33.322Z"
}
202: Accepted
Validation request was accepted and will resume asynchronously.
{
"id": "5d9f548b5b407ab2b9d12623",
"code": "MS_UNAVAILABLE",
"query": "IE6388047V",
"valid": null,
"valid_format": true,
"created": "2019-10-10T15:55:55.661Z",
"updated": "2019-10-10T15:55:55.661Z"
}
400: Bad Request
The VAT ID was not supplied in the body.
{
"code": "INVALID_INPUT",
"query": null,
"valid": false,
"valid_format": false
}

You may want to check valid_format on every request to give your customers feedback on their input. This boolean indicates whether your query was delivered in a valid format or not.

The validation result will be returned to you in the response. In the event that government services are temporarily unavailable, the API will respond with status code 202 and valid value null. Vatstack will retry unfulfilled validation requests asynchronously until a result has been obtained.

The id can be used to retrieve a validation status in future. Alternatively, you can obtain the status by checking the status in your dashboard, or listening to webhook events.

Finalized validation results are posted to you via webhooks. Unfulfilled validation requests will be abandoned if no result could be obtained after 2 days.

get
List all validations

https://api.vatstack.com/v1/validations
Retrieves all validation objects in order of creation, with the most recent appearing highest.
Request
Response
Request
Query Parameters
query
optional
string
The VAT number you want to search in the query field of your records.
requested_since
optional
string
Show only objects where the requested date is this date or later. Format YYYY-MM-DD.
requested_until
optional
string
Show only objects where the requested date is this date or earlier. Format YYYY-MM-DD.
batch
optional
string
Show only objects that belong to a batch with the given identifier.
limit
optional
number
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
page
optional
number
Integer for the current page.
Response
200: OK
Validation objects successfully retrieved.
{
"has_more": true,
"validations_count": 55,
"validations": [
{
"id": "5d1ded3128ca7a842aaf5ed4",
"company_address": "3RD FLOOR, GORDON HOUSE, BARROW STREET, DUBLIN 4",
"company_name": "GOOGLE IRELAND LIMITED",
"consultation_number": "WAPIAAAAW21qsOHW",
"country_code": "IE",
"query": "IE6388047V",
"type": "eu_vat",
"valid": true,
"valid_format": true,
"vat_number": "6388047V",
"requested": "2019-07-04T00:00:00.000Z",
"created": "2019-07-04T12:12:33.322Z",
"updated": "2019-07-04T12:12:33.322Z"
},
...
]
}

get
Retrieve a validation

https://api.vatstack.com/v1/validations/:id
Retrieves a validation object.
Request
Response
Request
Path Parameters
id
required
string
Identifier of the validation object to be retrieved.
Response
200: OK
Validation object successfully retrieved.
{
"id": "5d1ded3128ca7a842aaf5ed4",
"company_address": "3RD FLOOR, GORDON HOUSE, BARROW STREET, DUBLIN 4",
"company_name": "GOOGLE IRELAND LIMITED",
"consultation_number": "WAPIAAAAW21qsOHW",
"country_code": "IE",
"query": "IE6388047V",
"type": "eu_vat",
"valid": true,
"valid_format": true,
"vat_number": "6388047V",
"requested": "2019-07-04T00:00:00.000Z",
"created": "2019-07-04T12:12:33.322Z",
"updated": "2019-07-04T12:12:33.322Z"
}

Webhook Events

Vatstack will proactively notify your server as soon as a validation request was successfully processed and a result obtained from official government services. This means that you don’t have to query our API anymore and can instead listen to webhook events.

The payload contains the validation object which you can further process on your end. Configure at which endpoint they should be sent to in your dashboard. You could then reach out to the customer to rectify the situation or adjust your invoice for the next charge.

Event

Description

validation.succeeded

Received response from VIES. Check whether the VAT number is valid or not using the valid field.

Error Codes

Code

Description

INVALID_INPUT

VAT number is invalid.

INVALID_RESPONSE

The response obtained is invalid and cannot be processed.

INVALID_REQUESTER_INFO

Supplier VAT number is invalid. Verify that the VAT number entered in your account information is correct.

VAT_BLOCKED

VAT number has been blocked and cannot be queried.

GLOBAL_MAX_CONCURRENT_REQ

Maximum number of concurrent requests has been reached. Try to resubmit your request in a few moments.

MS_MAX_CONCURRENT_REQ

Maximum number of concurrent requests for this member state service has been reached. Try to resubmit your request in a few moments.

SERVICE_UNAVAILABLE

The validation service is currently unavailable. Your request has been saved and Vatstack will retry validations.

MS_UNAVAILABLE

A member state service is currently unavailable. Your request has been saved and Vatstack will retry validations.

TIMEOUT

Member state service could not be reached in time. Try to resubmit your request in a few moments.

SERVER_BUSY

The validation service is currently busy. Try to resubmit your request in a few moments.