About this endpoint
What it does
Validates up to 100 VAT numbers in one request against EU VIES, the Norwegian business register and the Swiss UID register, and returns one result row per number with its status and, where the register shares them, the registered name and address.
Request Body
| Parameter | Type | Description |
|---|---|---|
| vatNumbers | String Array | Required. VAT numbers with their country prefix, for example IE6388047V, DE811569869, EL094014201 (Greece), XI220430231 (Northern Ireland), NO923609016MVA (Norway) or CHE-116.281.710 MWST (Switzerland). Spaces, dots and dashes are ignored and prefixes are not case sensitive. Minimum 1 item, max 100 items. Empty values, hidden characters (zero-width space, BOM) and markup are rejected with 400. |
| defaultCountry | String | Two-letter country code used for numbers sent without a prefix, for example DE. Not case sensitive. An unknown code makes those rows invalid_format. |
| requesterVatNumber | String | Your own EU VAT number with prefix. When set, VIES returns a consultation_number for each EU check, and the result is always fetched live. Must be a valid EU VAT number format, otherwise the request fails with 400. |
Response
Returns a JSON object with count, billed and an items array with one row per distinct VAT number, in the order sent. Every row has the same fields; fields the register does not provide are null.
| Parameter | Type | Description |
|---|---|---|
| count | Integer | Number of rows in items. |
| billed | Integer | Provider-side count of rows that got a register answer. invalid_format and unavailable rows are not counted. ApyHub charges per call, not per row. |
| items | Object Array | One result per VAT number. |
| items[].input | String | The number as you sent it (leading and trailing spaces removed). |
| items[].status | ENUM | Allowed values: valid, invalid, invalid_format, unavailable. valid: registered. invalid: not registered. invalid_format: wrong layout or unknown prefix, checked locally with no upstream call. unavailable: the register did not answer; this is not a verdict on the number, retry later. |
| items[].valid | Boolean | true for valid, false for invalid and invalid_format, null for unavailable. |
| items[].country_code | String | Country code, for example IE, EL, XI, NO, CH. null when the prefix is unknown. |
| items[].country | String | Country name. null when the prefix is unknown. |
| items[].vat_number | String | The number without its country prefix. |
| items[].full_vat_number | String | The cleaned number with prefix, for example CHE116281710. null when the prefix is unknown. |
| items[].name | String | Registered name. null when the register does not share it (for example Germany and Spain) or the number is not valid. |
| items[].address | String | Registered address. Same conditions as name. |
| items[].source | String | Register that answered: EU VIES (European Commission), Bronnoysund Register Centre (Norway) or Swiss Federal UID register. null for invalid_format rows. |
| items[].consultation_number | String | VIES consultation number, only when requesterVatNumber is set and the number is an EU number. Otherwise null. |
| items[].error | String | Reason for an invalid_format or unavailable row (and some Norwegian invalid rows). null otherwise. |
| items[].note | String | Only present on some rows, for example when a member state does not share the name and address. |
| items[].bankrupt | Boolean | Norway only. Whether the company is registered as bankrupt. |
| items[].in_liquidation | Boolean | Norway only. Whether the company is in liquidation. |
| items[].checked_at | String | Time this row was produced, ISO 8601 UTC. |
| items[].source_checked_at | String | EU rows only. Time the register was actually queried. Earlier than checked_at when the answer was served from cache. |
| items[].response_ms | Integer | Upstream response time in milliseconds. 0 when served from cache or checked locally. |
Notes
- Repeated numbers in one request return a single row.
- UK (
GB) VAT numbers are not supported and returninvalid_format. - A request with exactly one number whose register does not answer returns
502withcode: upstream_unavailable; in a multi-number request the same number gets anunavailablerow instead. - Errors use one shape:
{"code": "invalid_input", "error": "...", "message": "..."}.



