VATify.eu API
Real-time query example

The API client sends an initial request, specifying the country and the company identifier in a JSON payload.

{
  "country": "Switzerland",
  "identifier": "CHE-109.409.488"
}
    

VATify.eu REST API responds with a 202 status, providing the ID of the newly initiated query. Note that the „Location“ header contains the URL of the API endpoint to poll for query results.

{
  "query": {
    "status": "IN_PROGRESS", 
    "id": "5TBx4hPmHf2O9ou4TY5K", 
    "subject": {
      "identifier": "CHE109409488", 
      "country_code": "CHE", 
      "country_name": "Switzerland"
    }, 
    "expires_at": "2022-03-24T10:07:43Z", 
    "expires_in": 3600, 
    "links": [
      {
        "href": "https://api.vatify.eu/v1/query/results/5TBx4hPmHf2O9ou4TY5K", 
        "method": "GET", 
        "rel": "poll"
      }
    ]
  }, 
  "result": {
    "ready": false, 
    "links": [
      {
        "href": "https://api.vatify.eu/v1/query/results/5TBx4hPmHf2O9ou4TY5K", 
        "method": "GET", 
        "rel": "self"
      }
    ]
  }, 
}
    

To check the current status of the query, the API client can send a GET request to the URL the server has provided with the initial response. This request can be made repeatedly (every few seconds) while waiting for the query results.

Unless information about the company in question has been cached recently, VATify.eu systems will contact upstream providers in real-time to retrieve the data. The results usually arrive in a few seconds, but may take up to a minute or two for some countries under some special circumstances.

While the query is still in progress, the response will be similar to the initial one.

{
  "query": {
    "status": "IN_PROGRESS", 
    "id": "5TBx4hPmHf2O9ou4TY5K", 
    "subject": {
      "identifier": "CHE109409488", 
      "country_code": "CHE", 
      "country_name": "Switzerland"
    }, 
    "expires_at": "2022-03-24T10:07:43Z", 
    "expires_in": 3598, 
    "links": [
      {
        "href": "https://api.vatify.eu/v1/query/results/5TBx4hPmHf2O9ou4TY5K", 
        "method": "GET", 
        "rel": "poll"
      }
    ]
  }, 
  "result": {
    "ready": false, 
    "links": [
      {
        "href": "https://api.vatify.eu/v1/query/results/5TBx4hPmHf2O9ou4TY5K", 
        "method": "GET", 
        "rel": "self"
      }
    ]
  }
}
    

But when the results are finally available, the server responds with a „200 OK“, providing the resulting company data within the JSON payload.

{
  "query": {
    "status": "FINISHED", 
    "id": "5TBx4hPmHf2O9ou4TY5K", 
    "subject": {
      "identifier": "CHE109409488", 
      "country_code": "CHE", 
      "country_name": "Switzerland"
    }, 
    "expires_at": "2022-03-24T10:07:43Z", 
    "expires_in": 3595, 
    "links": [
      {
        "href": "https://api.vatify.eu/v1/query/results/5TBx4hPmHf2O9ou4TY5K", 
        "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", 
          "_hr_registry_status": true, 
          "_uid_registry_status": true, 
          "_uid_registry_extension": "MWST"
        }, 
        "retrieval_date": "2022-03-24", 
        "retrieved_at": "2022-03-24T09:07:46Z", 
        "vatify_consultation_id": "4U0QHM-cLYOon-wExdND-wMlNxX-SKmoUw-Q2W5gZ"
      }
    ], 
    "links": [
      {
        "href": "https://api.vatify.eu/v1/query/results/5TBx4hPmHf2O9ou4TY5K", 
        "method": "GET", 
        "rel": "self"
      }
    ]
  }
}