VAT Number Validation API Documentation • Valdit

Now that you have an OAuth 2.0 Access Token you can validate your first VAT Number. Each API call requires you to send the Authorization token, in order to identify the caller of the API. As you may have already noticed in the result from the Access Token call, the Access Token is of type Bearer, so your HTTP requests to the API must include the Authorization header as follows:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz.......................

Make sure you insert the full token, which can be as long as a 1000 characters or more.

Next we need the VAT Number to check. An EU VAT Number consist of two parts, a two letter country code and the national number. Let’s take the number for SPA MONOPOLE, the manufacturers of the Belgian SPA mineral water, as an example. Their full VAT number is BE0420834005, so the country code is ‘BE’ and the national VAT number is ‘0420834005’. Note that the leading zero is required for this number.

You send the VAT number in a JSON body with the request, as indicated below:

{
"vatCountryCode": "BE",
"vatNumber": "0420834005"
}

Now we have the two parts to make the actual call. The raw HTTP request to send is:

 POST https://developer.valdit.com/api/v1/vatnumberchecks HTTP/1.1
 Host: developer.valdit.com 
 Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz.......................
 Content-Type: application/json
   
   {
    "vatCountryCode": "BE",
    "vatNumber": "0420834005"
   }

Or, using cURL:

 curl -X POST -H "Authorization: Bearer 
 eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz......................." -H "Content-Type: 
 application/json -d '{ 
    "vatCountryCode": "BE",
    "vatNumber": "0420834005"
    }
    ' "https://developer.valdit.com/api/v1/vatnumberchecks"

If all is well, the API will return a response with a HTTP response code 201 (Created). The body of the response will hold the information on the newly created Valdit Business Entity, including the structured address and the actual results of the VAT Number validation:

{
  "status": "success",
  "data": {
    "valditBusinessEntity": {
      "_id": "6dbfd244-c736-4fd7-8cca-e67da312efdf",
      "companyName": "SA S.A. SPA MONOPOLE, COMPAGNIE FERMIÈRE DE SPA",
      "vatNumberValidationInfo": {
        "vatCountryCode": "BE",
        "vatNumber": "0420834005",
        "lastCheckResult": "valid",
        "lastCheckDate": "2016-07-25T07:23:55.2096812Z",
        "vatRegisteredAddress": "RUE AUGUSTE LAPORTE 34\n4900 SPA",
        "vatNumberFormatValid": true,
        "vatCheckRecurrence": "none"
      },
      "businessAddress": {
        "street": "Rue Auguste Laporte",
        "houseNumber": 34,
        "postalCode": "4900",
        "city": "Spa",
        "countryCode": "BE",
        "formattedAddress": "Rue Auguste Laporte 34, 4900 Spa"
      }
    },
    "vatNumberChecks": [
      {
        "checkResult": "valid",
        "countryCode": "BE",
        "vatNumber": "0420834005",
        "companyName": "SA S.A. SPA MONOPOLE, COMPAGNIE FERMIÈRE DE SPA",
        "companyAddress": "RUE AUGUSTE LAPORTE 34\n4900 SPA",
        "checkDate": "2016-07-25T07:23:55.2096812Z",
        "consultationNumber": "WAPIAAAAVYg8EXul"
      }
    ]
  }
}

That’s it, you have made your first call to the API! You are now ready to use the retuned information. The next chapters contain detailed information on how you can use the API to make more advanced calls.

Validate a VAT Number