Validations

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

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

• Every response of type eu_oss_vat, eu_vat, and gb_vat includes a consultation number given by VIES and HMRC, respectively. The consultation number is a unique reference identifier and is an official piece of evidence used to show your tax office that you have rightfully validated a given VAT identification number on a given date.
• 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. You can attach an external_id to identify and query your records easily.
• ​Government service downtimes happen regularly but will be a less blocking issue from now on. Validation requests are gracefully accepted and enter a schedule for automated re-validation. You can identify downtimes by a response’s error code SERVICE_UNAVAILABLE. See error codes section for more information.
• 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

Create a Validation

Creates a validation object.

Request

Authorize with Public Key Secret Key

curl -X POST https://api.vatstack.com/v1/validations \
     -H "X-API-KEY: pk_live_6c46e7d65bc2caccdbf48f4a9c2fcba7" \

Body Parameters

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.

Response for Status Code 201 (Created)

Validation object successfully created.

{
  "id": "5d1ded3128ca7a842aaf5ed4",
  "active": true,
  "company_address": "3RD FLOOR, GORDON HOUSE, BARROW STREET, DUBLIN 4",
  "company_name": "GOOGLE IRELAND LIMITED",
  "company_type": null,
  "consultation_number": "WAPIAAAAW21qsOHW",
  "country_code": "IE",
  "external_id": null,
  "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"
}

Response for Status Code 202 (Accepted)

Validation request was accepted and will resume asynchronously.

{
  "id": "5d9f548b5b407ab2b9d12623",
  "active": null,
  "code": "SERVICE_UNAVAILABLE",
  "company_address": null,
  "company_name": null,
  "company_type": null,
  "consultation_number": null,
  "country_code": "IE",
  "external_id": null,
  "query": "IE6388047V",
  "type": "eu_vat",
  "valid": null,
  "valid_format": true,
  "vat_number": null,
  "requested": "2019-10-10T15:55:55.660Z",
  "created": "2019-10-10T15:55:55.661Z",
  "updated": "2019-10-10T15:55:55.661Z"
}

List all validations

Retrieves all validation objects in order of creation, with the most recent appearing highest.

Request

Authorize with Secret Key

curl -X GET https://api.vatstack.com/v1/validations \
     -H "X-API-KEY: sk_live_c283fd6d793076603646b197c7cb0424" \

Query Parameters

Response

Validation objects successfully retrieved.

{
  "has_more": true,
  "validations_count": 55,
  "validations": [
    {
      "id": "5d1ded3128ca7a842aaf5ed4",
      "active": true,
      "company_address": "3RD FLOOR, GORDON HOUSE, BARROW STREET, DUBLIN 4",
      "company_name": "GOOGLE IRELAND LIMITED",
      "company_type": null,
      "consultation_number": "WAPIAAAAW21qsOHW",
      "country_code": "IE",
      "external_id": null,
      "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"
    },
    ...
  ]
}

Retrieve a Validation

Retrieves a validation object by the :id path parameter.

Request

Authorize with Secret Key

curl -X GET https://api.vatstack.com/v1/validations/:id \
     -H "X-API-KEY: pk_live_6c46e7d65bc2caccdbf48f4a9c2fcba7" \

Response

Validation object successfully retrieved.

{
  "id": "5d1ded3128ca7a842aaf5ed4",
  "active": true,
  "company_address": "3RD FLOOR, GORDON HOUSE, BARROW STREET, DUBLIN 4",
  "company_name": "GOOGLE IRELAND LIMITED",
  "company_type": null,
  "consultation_number": "WAPIAAAAW21qsOHW",
  "country_code": "IE",
  "external_id": null,
  "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"
}

Delete a Validation

Deletes a validation object by the :id path parameter. Note that validation objects with the eu_vat type can only be deleted after 24 hours.

Request

Authorize with Secret Key

curl -X DELETE https://api.vatstack.com/v1/validations/:id \
     -H "X-API-KEY: sk_live_c283fd6d793076603646b197c7cb0424" \

Response

Validation object successfully deleted.

{
  "id": "5d1ded3128ca7a842aaf5ed4",
  "deleted": true
}

VAT ID Number Formats

Vatstack currently validates the following types of VAT identification numbers in real-time:

• Australia: Business Number or Company Number (au_gst)
• European Union: VAT ID and EORI of EU businesses (eu_vat and eu_eori)
• European Union (OSS): One-Stop Shop ID of non-EU businesses (eu_oss_vat)
• Norway: Organization Number (no_vat)
• Singapore: GST Registration Number (sg_gst)
• Switzerland: Business Identification Number (ch_vat)
• United Kingdom: VAT ID and EORI of UK businesses (gb_vat and gb_eori)

If you are looking to test VAT IDs before deploying for production, refer to our testing documentation. Below section explains how you can submit validation requests for each region.

Australia

Australia’s GST number format is a 11 digit number formed from a 9 digit unique identifier and 2 leading check digits. The identifier is issued to all entities registered in the Australian Business Register (ABR). It is therefore also known as the Australian Business Number (ABN). Example 51 824 753 556.

Validate an ABN, or ACN by providing 11 digits, or 9 digits, respectively in your request. Vatstack automatically checks against the ABR whether the business or company is registered for GST. Our announcement has more information about ABN or ACN validation.

European Union (VIES)

The API validates both the VAT ID of EU businesses and the OSS ID of non-EU businesses. The VAT ID format starts with the country code of the Member State, followed by 8 to 12 digits or characters. Note that the country code is a two-letter ISO 3166 alpha-2, except for Greece for which the abbreviation is ‘EL’. Example EL999999999.

The OSS ID format starts with ‘EU’, followed by 9 digits. The country code of non-EU businesses cannot be determined and is always null. Example EU999999999.

Learn more about the benefits of validating EU VAT numbers with Vatstack.

Norway

Businesses which are registered in the Value Added Tax Register are required to add the letters ‘MVA’ as a suffix to their organization number. The organization number has 9 digits. Example 999999999MVA.

Vatstack detects a Norwegian VAT ID by its suffix ‘MVA’ in your request and validates it against the Central Coordinating Register. Our announcement has more details about Norwegian VAT number validations.

Switzerland

Swiss number formats are based on the Swiss UID. It starts with ‘CHE’, followed by 9 digits, and either ends with ‘MWST’, ‘TVA’ or ‘IVA’ depending on the part of Switzerland a business is registered in. Example CHE-123.456.789 MWST.

Provide a VAT ID with a ‘CHE’ prefix in your request, and Vatstack will automatically validate it against the official UID Register. Learn more about Swiss VAT number validations in our announcement.

United Kingdom

UK’s VAT ID format is a 9 or 12 digit number. It may or may not be preceded by ‘GB’ as a remnant of being part of the EU where all registration numbers are preceded by their respective country codes. Example 123456789.

Learn more about UK VAT number validations in our announcement.

Webhook Events

Vatstack can proactively notify your webhooks endpoint as soon as a validation request was processed. This means that you don’t have to query our API for changes anymore and can instead listen to webhook events. You could then reach out to the customer after receiving an event from Vatstack to rectify tax treatments for the next charge.

See our webhooks reference for more information.

Error Codes