# EU VAT Batch Validator (VIES) with outage-aware retries (`vibement/eu-vat-batch-validator`) Actor

Validate EU VAT numbers in bulk against the official VIES service. Normalizes messy input, runs concurrently, and automatically retries when a member state's server is temporarily unavailable.

- **URL**: https://apify.com/vibement/eu-vat-batch-validator.md
- **Developed by:** [Vibement Labs](https://apify.com/vibement) (community)
- **Categories:** Agents, Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## EU VAT Batch Validator (VIES)

Validate EU VAT numbers in bulk against the **official VIES service** run by the European Commission — and get a straight answer even when a member state's server is down.

### Why this exists

VIES is the only authoritative source for EU VAT validation, but it has a well-known problem: **individual member states go offline regularly.** When Germany's node is down, VIES returns `MS_UNAVAILABLE` — and most tools quietly treat that as "invalid" or just fail the row.

That's a dangerous mistake. **A VAT number that could not be checked is not an invalid VAT number.** If you block a customer, refuse a reverse-charge invoice, or drop a lead because of it, the error is yours.

This Actor never conflates the two:

| Result | What it means |
|---|---|
| `VALID` | VIES confirmed it, with the registered name and address |
| `INVALID` | VIES actively said this number is not registered |
| `MS_UNAVAILABLE` / `TIMEOUT` | The member state did not answer. **Retried with exponential backoff first.** Treat as "unknown", not "invalid" |
| `UNKNOWN_COUNTRY` | No EU country prefix found — and we don't charge you for these |

### What it does

- **Bulk** — pass a list, it validates them concurrently (default 4 parallel, tunable)
- **Forgiving input** — `IE6388047V`, `IE 6388047 V`, `ie-6388047v` all work. `GB` is mapped to `XI` (Northern Ireland) automatically, since Great Britain left VIES after Brexit
- **Automatic retries** — member-state outages are retried with exponential backoff and jitter before giving up
- **Structured output** — country, number, status, validity, registered name, registered address, attempt count, timestamp

### Input

```json
{
  "vatNumbers": ["IE6388047V", "NL810195835B01", "FR40303265045"],
  "defaultCountry": "",
  "concurrency": 4,
  "maxRetries": 4
}
```

`defaultCountry` is used for numbers with no prefix (e.g. `6388047V` with `defaultCountry: "IE"`).

### Output

```json
{
  "input": "IE6388047V",
  "countryCode": "IE",
  "vatNumber": "6388047V",
  "status": "VALID",
  "isValid": true,
  "name": "GOOGLE IRELAND LIMITED",
  "address": "3RD FLOOR, GORDON HOUSE, BARROW STREET, DUBLIN 4",
  "attempts": 1,
  "checkedAt": "2026-09-23T00:00:00.000Z",
  "error": null
}
```

A `SUMMARY` record (total / valid / invalid / unresolved) is written to the key-value store.

### Pricing

Pay per event. **You are charged only for numbers actually submitted to VIES** — empty rows and numbers with no recognisable EU country prefix are filtered out for free, and retries of a single number count as one charge.

### Coverage

All 27 EU member states plus `XI` (Northern Ireland). Data comes directly from VIES; this Actor does not cache or resell results.

### Notes

- VIES is a government service with its own rate limits. Keep concurrency modest (4–6) for large batches.
- VIES returns the registered name and address only for member states that choose to publish them; some return `---`, which this Actor normalises to `null`.

# Actor input Schema

## `vatNumbers` (type: `array`):

VAT numbers to validate. Any common format works: 'IE6388047V', 'IE 6388047 V', 'ie-6388047v'. Include the 2-letter country prefix, or set defaultCountry below.

## `defaultCountry` (type: `string`):

Used when a VAT number has no country prefix (e.g. '6388047V' with defaultCountry 'IE').

## `concurrency` (type: `integer`):

How many different member states to query at the same time. Numbers from the SAME country are always queried one at a time, because VIES rate-limits per member state.

## `maxRetries` (type: `integer`):

VIES member-state servers go offline regularly (MS\_UNAVAILABLE). This many retries with exponential backoff before giving up.

## Actor input object example

```json
{
  "vatNumbers": [
    "IE6388047V",
    "NL810195835B01",
    "DE811907980"
  ],
  "defaultCountry": "",
  "concurrency": 4,
  "maxRetries": 4
}
```

# Actor output Schema

## `results` (type: `string`):

One record per submitted VAT number: status, validity, registered name and address, and how many attempts it took.

## `dataset` (type: `string`):

All validation records as a dataset.

## `summary` (type: `string`):

Totals for the run: how many were valid, invalid, and unresolved because a member state was offline.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "vatNumbers": [
        "IE6388047V",
        "NL810195835B01",
        "DE811907980"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("vibement/eu-vat-batch-validator").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "vatNumbers": [
        "IE6388047V",
        "NL810195835B01",
        "DE811907980",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("vibement/eu-vat-batch-validator").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "vatNumbers": [
    "IE6388047V",
    "NL810195835B01",
    "DE811907980"
  ]
}' |
apify call vibement/eu-vat-batch-validator --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vibement/eu-vat-batch-validator"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/BdLFkHlfV6mxruYXX/builds/AD6UQAwAPO38ThHHG/openapi.json