# VAT Number Validations {% hint style="danger" %} VatZen is Deprecated since January 2022 and API server will be shut down soon! {% endhint %} We obtain company's informations directly from different official sources, such as EU commissions DB and local countries databases. All subscription plans are allowed to perform real-time VAT ID validations and company information lookups through the `validate` and `validations` API endpoints. ### Hot and Cold Validations At VatZen we have a concept of 2 validations types: Hot and Cold. * **Cold** validation works in fire and forget way. Meaning that you simply call our endpoint and we return you the data, which is never stored afterwards. * **Hot** validation is different from the cold one in the way that all the requests you make has id's assigned and stored in our DB. And you can always fetch this validations (fetch them all of fetch by id). Cold validations are performed via `validate` endpoint, end hot validation use `validations` CRUD endpoint. You can get more details below. ### Using Requester Data When validating VAT number, EU commission database can return you reference id, which you can then use in your reports or during the audit process. In order to obtain this reference number, you have to provide requested VAT number, meaning the number of your company. In order to do that, simply go to VatZen's dashboard and fill the VAT Number option on the settings page: Consultation number is used if you want to be able to prove to a Tax Administration of a Member State that you have checked a given VAT number at a given time, and obtained a given validation reply. ### Validation Entity Base of the validations endpoints is the `Validation` entity, which is returned from all validations-related endpoint. You can find the description of the `Validation` entity below: | Key | Type | Example | Description | | ------------------------ | ------------------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | `String` or `null` | `1234` | Uniq ID of the validation. Only applies to Hot validations. You can use it afterwards to obtain validation information. | | `consultation_number` | `String` | `WAPIAAAAXQ6Sc` | Consultation number returned by VIES system. | | `valid` | `Boolean or null` | `true` | Represents the validity of VAT number in the query. `true` only when it's valid. Null if we were unable to check the validity due to the government services being down. | | `requested` | `String` | `2020-08-29+02:00` | Requested date returned from VIES system | | `query` | `String` | `LU26375245` | Original query from the request. | | `country` | `Object or null` | --- | Information about the country of the company. | | `country.code` | `String` | `LU` | ISO country code | | `country.name` | `String` | `Luxembourg` | Name of the country | | `country.local_name` | `String` | `Luxembourg` | Local name of the country, falls back to English | | `country.member_state` | `Boolean` | `true` | If the country member state or not | | `company` | `Object` or `null` | --- | Information about the company. Sometimes this information is private, so we'll show `null` | | `company.name` | `String` | `AMAZON EUROPE CORE S.A R.L.` | Company's name | | `company.address` | `String` | `38, AVENUE JOHN F. KENNEDY, L-1855 LUXEMBOURG` | Company's address | | `pending` | `Boolean` | `false` | If the government service is down, we return pending request, which we'll fullfill later. You can get the result by fetching validation by id. | | `valid_format` | `Boolean` | `true` | If the VAT format from the query valid | | `requester` | `Object` or `null` | --- | Information about your company - requester | | `requester.country_code` | `String` | `LU` | Country code | | `requester.vat_number` | `String` | `26375245` | VAT Number | ## Validate VAT Number `GET` `https://api.vatzen.com/v1/validate/:number` #### Path Parameters | Name | Type | Description | | ------ | ------ | ------------------------------------------- | | number | string | VAT Number of business you want to validate | {% tabs %} {% tab title="200 Successfully validated" %} ```javascript { "success": true, "consultation_number": "WAPIAAAAXQ6S", "valid": true, "requested": "2020-08-29+02:00", "query": "LU26375245", "country": { "code": "LU", "name": "Luxembourg", "local_name": "Luxembourg", "member_state": true }, "company": { "name": "AMAZON EUROPE CORE S.A R.L.", "address": "38, AVENUE JOHN F. KENNEDY, L-1855 LUXEMBOURG" }, "pending": false, "valid_format": true, "requester": { "country_code": "LU", "vat_number": "26375245" } } ``` {% endtab %} {% endtabs %} ## Response [Validation Entity](/api/validate-vat-number.md#validation-entity) or [API Error](/api-errors.md) will be returned. ## Create Validation `POST` `https://api.vatzen.com/v1/validations` Creates a new hot validation and stores it in our db. ID is assigned to every validation. #### Query Parameters | Name | Type | Description | | ----------- | ------ | ------------------------------- | | vat\_number | string | VAT Number you want to validate | {% tabs %} {% tab title="200 " %} ```javascript { "success": true, "id": "string", "consultation_number": "string", "requested": "string", "created": "string", "valid": true, "query": "string", "country": { "code": "DE", "name": "Germany", "local_name": "Deutschland", "member_state": true }, "company": {}, "pending": true, "valid_format": true, "requester": {} } ``` {% endtab %} {% endtabs %} ## Get All Validations `GET` `https://api.vatzen.com/v1/validations` Returns all the validation you performed with your token, paginated. Can be useful for exporting your activity. #### Query Parameters | Name | Type | Description | | ----- | ------- | ------------------------------------------ | | page | integer | Page number. Default to 1. | | limit | integer | Limit used for pagination. Default to 100. | {% tabs %} {% tab title="200 All the validation returned" %} ```javascript { "success": true, "pagination": { "has_more": false, "total_count": 3 }, "validations": [ { "id": "5f45015c04725a4f76e07d", "valid": true, "requested": "2020-08-25+02:00", "created": "2020-08-25T12:17:32.370Z", "query": "NL852071589B01", "country": { "code": "NL", "name": "Netherlands", "local_name": "Netherlands", "member_state": true }, "company": { "name": "UBER B.V.", "address": ", MR. TREUBLAAN 00007, 1097DP AMSTERDAM, " }, "pending": false, "valid_format": true, "requester": null } //.... ] } ``` {% endtab %} {% endtabs %} ## Get Validation By ID `GET` `https://api.vatzen.com/v1/validations/:id` Returns the single validation by id. You can use it to retrieve information about pending validation, of for the validation for the specific transaction. #### Path Parameters | Name | Type | Description | | ---- | ------ | -------------------------------------------------- | | id | string | Validation ID you want to obtain information about | {% tabs %} {% tab title="200 " %} ```javascript { "success": true, "id": "5f45015c04725a4f76e07", "valid": true, "requested": "2020-08-25+02:00", "created": "2020-08-25T12:17:32.370Z", "query": "NL852071589B01", "country": { "code": "NL", "name": "Netherlands", "local_name": "Netherlands", "member_state": true }, "company": { "name": "UBER B.V.", "address": ", MR. TREUBLAAN 00007, 1097DP AMSTERDAM, " }, "pending": false, "valid_format": true, "requester": null } ``` {% endtab %} {% endtabs %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://documentation.vatzen.com/api/validate-vat-number.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.