VATify.eu API
Get started

image/svg+xml [example] VATify.eu REST API Client application POST /v1/query (country, company-id) GET /v1/query/results/<query-id> 202 Accepted (query-id) 200 OK (company data) [example] [example] [example]

Introduction

VATify.eu API is a modern REST-like application programming interface that uses stan­dard JSON format to exchange messages over TLS-encrypted HTTPS protocol. Client-side software implementation should feel reasonably straight-forward to most web de­ve­lo­p­ers and people familiar with REST.

The API currently supports live/real-time acquisition of basic com­pany in­for­ma­ti­on, with data being sourced at vari­ous offi­ci­al autho­ri­ties and other pro­vi­ders (see data sources). Unless data for a specific com­pany were cached recently, VATify.eu systems will contact the authoritative sources in real time to access the required in­for­ma­ti­on, process it, and make the result avai­la­ble to the API caller. De­pen­ding on the sources used, this may take up to a minute or two (but takes only a few seconds for most coun­tries in most cir­cum­stances, see the average response times).

Such delays must be taken into consideration when designing client software, especially user interfaces. However, the API makes integration easier by splitting the procedure into multiple calls – one to start the query, and others to check its status and/or get the results.

VATify.eu API basics

Currently, version 1 of the API is the one you can use. It is avai­la­ble under the following root URL:
https://api.vatify.eu/v1

Client software communicates with the VATify.eu API by performing API calls. These are just stan­dard HTTP re­quests to special URL addresses known as the API endpoints. De­pen­ding on the target endpoint, an API call must use the correct verb (i.e., HTTP method, usually GET or POST), provide the appropriate HTTP header fields and (if required) carry a JSON payload as the re­quest body. Such basic web-client func­ti­o­na­lity is well supported in popular programming languages and de­ve­lop­ment environments.

The „Accept“ and „Content-Type“ header fields are not strictly required in your HTTP re­quests. If missing, the payload will be sent/in­ter­preted by the API as a UTF-8 encoded JSON do­cu­ment.

To make JSON response payloads easier to read by humans (using indentation and newlines), append the format=human query parameter to the endpoint URL. For example:
https://api.vatify.eu/v1/query/results/EsmNAdZnCwbshE4phe18?format=human

The „demo“ API

For regular operation, API clients must possess valid credentials and be able to obtain access tokens. A special demo API is avai­la­ble that doesn't have these re­qui­re­ments. It can be used without au­tho­ri­za­tion, and even directly with a web browser (HTTP GET re­quests are allowed where POST is normally required).

URL addresses for demo endpoints can be found by inserting the demo/ path com­po­nent imme­di­a­te­ly after the v1/ version com­po­nent. For example:
instead of the stan­dard endpoint:https://api.vatify.eu/v1/query ,
you can use this demo endpoint:https://api.vatify.eu/v1/demo/query .

The demo API is limited to a predefined list of com­pa­nies (avai­la­ble here). Any other com­pany is considered non-existing. In most cases, the demo API also returns old/stale data that has been cached many days ago.

Get client credentials

Note: if using the demo API only, you may skip this step (see The „demo“ API above).

To start using the API, you must first obtain your client credentials:
  1. Create an API account and sign in to this account.
  2. Select the „Client credentials“ tab (usually already selected) and click on the „Add new client“ button. A new row will appear at the bottom of the table.
  3. Type in a custom name for your client as you see fit. For example, a name could be a reference to a user, a customer or a software application.
  4. You can now find the new client's ID (a.k.a. the username) under the „Client ID“ column.
  5. To get the access key (a.k.a. the pass­word), click on the „Show access key“ button.

Note that the access key will be shown only once and we can never show you the same key again (we only store a one-way encrypted version). The key can be changed at any time, however.

Get a bearer token
(example code:  Javascript, PHP, Python)

Note: if using the demo API only, you may skip this step (see The „demo“ API above).

image/svg+xml REST API Client app POST /v1/oauth2/token (credentials) 200 OK (bearer token) [example] [example]

VATify.eu API uses OAuth 2.0 „Client Credentials Flow“ for au­then­ti­ca­tion and au­tho­ri­za­tion. To make API calls, your integration must first obtain a bearer token. The bearer token is a secret string that authorizes you to use the API for a limited amount of time (usually 4 hours).

To exchange your (long-term) client ID and access key for this (time-limited) bearer token, you must make an HTTP POST re­quest to the API au­then­ti­ca­tion endpoint:
https://api.vatify.eu/v1/oauth2/token

The variable grant_type with a value of client_credentials should be sent in this re­quest's body (payload). The re­quest must also include an „Au­tho­ri­za­tion“ header pro­vi­ding your client ID and access key as per the HTTP basic au­then­ti­ca­tion specification. This is one of the most common ways to au­then­ti­ca­te via HTTP and should be well supported by web-client libraries in popular programming languages.

Here is an example of how to get a bearer token using cURL:

curl -v POST https://api.vatify.eu/v1/oauth2/token \
  -u '<CLIENT-ID>:<ACCESS-KEY>' \
  -H 'Content-Type: application/json' \
  -d '{ "grant_type": "client_credentials" }'

The result should be a „200 OK“ response with a JSON do­cu­ment as its body (payload).

Below is a response payload sample. The access_token string is the newly ge­ne­ra­ted bearer token, and expires_in is the number of seconds before the token expires.

{
  "scope": "vatifyeu_query",
  "access_token": "QXsVKAUwu3am1ekiNlUni7QPIxqSZ6qhRbay",
  "token_type": "Bearer",
  "created_at": "2022-03-02T11:44:30Z",
  "expires_at": "2022-03-02T15:44:29Z",
  "expires_in": 14399
}

Note that refresh/renewal tokens are not in use by the VATify.eu API. A new bearer token can be obtained by simply repeating the same API call again.

Start a VATify.eu query
(example code:  Javascript, PHP, Python)

After a bearer token has been successfully obtained, it can be used to make REST API calls.

Note: the demo API can be used without a bearer token, but only for testing (see The „demo“ API above).

One of the basic API calls is to run a VATify.eu real-time query. The caller provides a com­pany ID and the coun­try where this com­pany is registered, and VATify.eu systems will retrieve basic in­for­ma­ti­on about the com­pany from upstream offi­ci­al sources. De­pen­ding on the sources used, this may take up to a few minute or two (but takes only a few seconds in most cir­cum­stances).

To run a VATify.eu real-time query, you should send a POST re­quest to the REST API's query endpoint:
https://api.vatify.eu/v1/query

The re­quest payload must be a JSON do­cu­ment con­tai­ning the variables coun­try (pro­vi­ding the coun­try name or ISO-3166 coun­try code) and identifier (pro­vi­ding the com­pany identifier). The identifier is usually a VAT-ID or a registration number, but this de­pends on the coun­try (see data sources for more in­for­ma­ti­on).

Here is a cURL example for running a query:

curl -v POST https://api.vatify.eu/v1/query \
  -H 'Authorization: Bearer <BEARER-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "country": "<COUNTRY-NAME>", "identifier": "<COMPANY-IDENTIFIER>" }'

Alternatively (but not recommended), the same API call can be made via the (incorrect) HTTP GET method, pro­vi­ding input variables as query parameters within the URL. Using the demo API, not even a valid bearer token is required, and testing with only a web browser is po­ssi­ble. For example:
https://api.vatify.eu/v1/demo/query?coun­try=Switzerland&identifier=CHE-109.409.488

Note: due to caching, demo queries usually take less time than regular queries. The demo API thus recognizes a special query parameter delay which can be used to specify the minimum time (in seconds) that must pass before the results become avai­la­ble. You can use this to simulate a long-running query. For example:
https://api.vatify.eu/v1/demo/query?coun­try=Switzerland&identifier=CHE-109.409.488&delay=5

The result of your re­quest will be a „202 Accepted“ response with a JSON payload reporting the query status as „IN_PROGRESS“ and result readiness as false. A sample is avai­la­ble below:

{
  "query": {
    "status": "IN_PROGRESS",
    "id": "mnb6W4JJdsy3HgwLnAUc",
    "subject": {
      "identifier": "CHE109409488",
      "country_code": "CHE",
      "country_name": "Switzerland"
    },
    "expires_at": "2022-03-04T13:08:57Z",
    "expires_in": 3600,
    "links": [
      {
        "href": "https://test.api.vatify.eu/v1/query/results/mnb6W4JJdsy3HgwLnAUc",
        "method": "GET",
        "rel": "poll"
      }
    ]
  },
  "result": {
    "ready": false,
    "links": [
      {
        "href": "https://test.api.vatify.eu/v1/query/results/mnb6W4JJdsy3HgwLnAUc",
        "method": "GET",
        "rel": "self"
      }
    ]
  }
}

The „Location“ header field of this HTTP response points to the URL of the API endpoint that should be polled while waiting for query results. The same URL is avai­la­ble under the links key in JSON dictionaries query and result (see the above example).

Get VATify.eu query results
(example code:  Javascript, PHP, Python)

The HTTP response rece­ived when starting the VATify.eu query includes the URL of the endpoint that should be polled while waiting for results (see above). To check the status of the query and (when finished) retrieve the results, you should send a GET re­quest to this URL. This should be done repeatedly, until the result is avai­la­ble.

For example (using cURL):

curl -v GET https://api.vatify.eu/v1/query/results/<QUERY-ID> \
  -H 'Authorization: Bearer <BEARER-TOKEN>'

While the query is still in progress, the response will be similar to the one rece­ived when starting the query, with HTTP status being „202 Accepted“, query status „IN_PROGRESS“ and result readiness false (see the example above).

But when query results become avai­la­ble, you should rece­ive a „200 OK“ response. Query status will be marked as „FINISHED“ and result will be ready (true). The re­quested com­pany in­for­ma­ti­on will be included under the result's items array:

{
  "query": {
    "status": "FINISHED",
    "id": "rYoHE5i5DVdiUVp8fuyZ",
    "subject": {
      "identifier": "CHE109409488",
      "country_code": "CHE",
      "country_name": "Switzerland"
    },
    "expires_at": "2022-03-04T17:10:14Z",
    "expires_in": 3591,
    "links": [
      {
        "href": "https://test.api.vatify.eu/v1/query/results/rYoHE5i5DVdiUVp8fuyZ",
        "method": "GET",
        "rel": "poll"
      }
    ]
  },
  "result": {
    "ready": true,
    "items": [
      {
        "data": {
          "identifier": "109409488",
          "status": "OK",
          "vat_status": "VALID",
          "title": "STUDIO MODERNA SA",
          "address": "Via Industrie 25",
          "city": "Giubiasco",
          "community": "Bellinzona",
          "region": "TI",
          "country": "Switzerland",
          "postal_code": "6512",
          "community_code": "5002",
          "country_code": "CHE",
          "registration_number": "CH51430258162",
          "vat_registration_date": "2003-04-01",
          "tax_id_number": "CHE-109.409.488",
          "sector": "62.010",
          "_hr_registry_status": true,
          "_uid_registry_status": true,
          "_uid_registry_extension": "MWST"
        },
        "retrieval_date": "2022-03-03",
        "retrieved_at": "2022-03-03T22:00:32Z",
        "vatify_consultation_id": "POwVa5-c0yWPY-Is1jE2-V5wNiR-6F9uTj-YeNa8R"
      }
    ],
    "links": [
      {
        "href": "https://test.api.vatify.eu/v1/query/results/rYoHE5i5DVdiUVp8fuyZ",
        "method": "GET",
        "rel": "self"
      }
    ]
  }
}


Please note:

  • Only the identifier, status and vat_status fields are guaranteed to be avai­la­ble for every com­pany. The presence and scope of the rest of the dataset de­pends on the in­for­ma­ti­on VATify.eu systems are able to retrieve from upstream pro­vi­ders in each coun­try (see data sources). In most cases, however, at least the com­pany name and address will also be avai­la­ble.

  • In some cir­cum­stances, the items array may contain more than one com­pany. For example, the Bosnia and Herzegovina's unified com­pany register is comprised of 3 separate/independent registers, and multiple com­pa­nies may be found even if searching with a sin­gle identifier.