# EU VAT Number Validator (VIES) - Bulk Check (`gufobyte/eu-vat-validator`) Actor

Validate thousands of EU VAT numbers in bulk with the official VIES API. Free offline syntax pre-check, automatic retries when a country is down, company name and address, consultation number for audit trails. CSV, Excel, JSON.

- **URL**: https://apify.com/gufobyte/eu-vat-validator.md
- **Developed by:** [Gufobyte](https://apify.com/gufobyte) (community)
- **Categories:** Business, Lead generation
- **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 Number Validator (VIES) - Bulk Check

Validate **hundreds or thousands of EU VAT numbers in one run** against the European Commission's official **VIES** service. Get back a clean table with the validity status, the registered **company name and address** (where the member state discloses it), and, optionally, the official **VIES consultation number** you can keep as proof of due diligence.

Built for e-commerce teams, accountants, finance/ops, marketplaces and CRM clean-up jobs that need a reliable, auditable **VAT ID check** without writing code.

### What does EU VAT Number Validator do?

- ✅ **Bulk VAT validation** of all 27 EU member states + Northern Ireland (XI) through the official VIES REST API
- 🧹 **Normalises messy input**: `de 811-569.869`, `GR094259216` (mapped to `EL`), bare Italian *partita IVA* with a default country
- 🆓 **Free offline syntax pre-check** per country (plus the Italian check digit): malformed numbers are flagged instantly and **never charged**
- 🔁 **Automatic retries with back-off** when a national VIES node is busy or down (`MS_UNAVAILABLE`, `MS_MAX_CONCURRENT_REQ`...): numbers that still can't be verified are reported, **not charged**
- 🧾 **Consultation number** (`requestIdentifier`) when you provide your own VAT number - handy for intra-community supply evidence
- 🧮 **Deduplication** so you never pay twice for the same number
- 📤 Export to **CSV, Excel, JSON, XML**, or pull results via API, Make, Zapier, n8n, Google Sheets

### Why use it?

- **Check a supplier or customer list before invoicing** (reverse charge needs a valid VAT ID)
- **Clean your CRM/ERP**: find dead or mistyped VAT numbers in bulk
- **Monthly compliance re-checks**: schedule the Actor and get only the numbers that became invalid
- **Onboarding/KYB in marketplaces**: validate sellers' VAT IDs automatically through the API

### How much does it cost?

This Actor uses **pay-per-event** pricing: you pay only for numbers that received a **definitive answer from VIES** (valid or invalid).

| Event | Price |
|---|---|
| VAT number checked (valid or invalid answer from VIES) | **$3.00 per 1,000** ($0.003 each) |
| Syntax error, duplicate, or country service unavailable | **free** |

Example: 2,000 numbers, of which 50 are malformed and 30 can't be reached → you pay for 1,920 checks = **$5.76**. Set a *Maximum cost per run* in the run options and the Actor stops cleanly when it is reached.

### How to use it

1. Click **Try for free**.
2. Paste your VAT numbers in **VAT numbers** (one per line), or send them via API.
3. Optionally set **Default country code** (for bare numbers) and **Your own VAT number** (to get consultation numbers).
4. Click **Start** and download the results from the **Output** tab.

### Input

```json
{
  "vatNumbers": ["IE6388047V", "DE 811 569 869", "00743110157", "FR123"],
  "defaultCountryCode": "IT",
  "requesterVatNumber": "",
  "deduplicate": true,
  "includeSyntaxErrors": true,
  "maxConcurrency": 3,
  "maxRetries": 4
}
```

| Field | Description |
|---|---|
| `vatNumbers` | List of VAT numbers, with or without country prefix (required) |
| `defaultCountryCode` | Country applied to numbers without prefix |
| `requesterVatNumber` | Your own EU VAT number, to receive an official consultation number |
| `deduplicate` | Check each normalised number once (default `true`) |
| `includeSyntaxErrors` | Output a free row for malformed numbers (default `true`) |
| `maxConcurrency` | Parallel requests to VIES (1-10, default 3) |
| `maxRetries` | Retries when a member state is busy/unavailable (0-8, default 4) |

### Output

One row per input number. Example:

```json
{
  "input": "IE6388047V",
  "vatNumber": "IE6388047V",
  "countryCode": "IE",
  "nationalNumber": "6388047V",
  "syntaxValid": true,
  "status": "valid",
  "valid": true,
  "name": "GOOGLE IRELAND LIMITED",
  "address": "3RD FLOOR, GORDON HOUSE, BARROW STREET, DUBLIN 4",
  "consultationNumber": null,
  "viesRequestDate": "2026-10-08T03:52:30.511Z",
  "errorCode": null,
  "attempts": 1,
  "checkedAt": "2026-10-08T03:52:30+00:00",
  "source": "VIES (European Commission)"
}
```

`status` is one of `valid`, `invalid`, `syntax_error`, `service_unavailable`, `error`. A run summary (counts per status) is saved in the key-value store under `SUMMARY`.

The dataset has two views: **Overview** and **Needs attention** (invalid, malformed or unverifiable numbers only).

### Tips

- Some countries (e.g. Germany, Spain) **do not disclose name/address** through VIES: you still get the validity status.
- VIES national nodes have maintenance windows. If you see `service_unavailable`, re-run later with just those numbers - they were not charged.
- Keep `maxConcurrency` at 3-5: VIES throttles bursts, and higher values usually cause more retries, not more speed.

### Is it legal? Where does the data come from?

All data comes from the **public VIES service of the European Commission**, queried through its official REST API, one request per number, exactly as the public VIES web form does. No scraping, no login, no third-party databases. Names and addresses of sole traders can be personal data under GDPR: process them only for a legitimate purpose (e.g. invoicing and tax compliance).

VIES itself states that a VIES response is not a legal certificate; for disputes, contact the competent national tax authority.

### Integrations and API

Run it from the Apify API, the Apify Python/JS clients, or connect it with Make, Zapier, n8n, Google Sheets, Slack and webhooks. Schedule a weekly run to re-validate your customer base.

### FAQ and support

- **Can I validate UK (GB) numbers?** No, GB left VIES in 2021. Northern Ireland traders (`XI`) are supported.
- **Something broke?** Open an issue in the **Issues** tab - we usually answer within 24 hours.

*Made by Gufobyte - small, honest data tools.*

# Changelog

This Actor's version history is a separate document: https://apify.com/gufobyte/eu-vat-validator/changelog.md

# Actor input Schema

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

One VAT number per line. Spaces, dots and dashes are ignored. Use the VIES country prefix (e.g. DE, FR, IT, EL for Greece, XI for Northern Ireland). GR is accepted as an alias for EL.

## `defaultCountryCode` (type: `string`):

Used for numbers that have no country prefix, e.g. IT for a list of bare Italian partite IVA. Leave empty to require a prefix.

## `requesterVatNumber` (type: `string`):

If you provide your own EU VAT number, VIES returns an official consultation number for every check, which you can keep as proof of due diligence for intra-community supplies.

## `deduplicate` (type: `boolean`):

Check each normalised VAT number only once (you are only charged once).

## `includeSyntaxErrors` (type: `boolean`):

Output a row (free of charge) for numbers that fail the offline format check, so your output matches your input list.

## `maxConcurrency` (type: `integer`):

VIES throttles bursts. 3 is a safe default; higher values may cause more retries.

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

How many times to retry when a member state service is busy or unavailable (with exponential back-off).

## Actor input object example

```json
{
  "vatNumbers": [
    "IE6388047V",
    "DE 811 569 869",
    "IT00000000000",
    "FR123"
  ],
  "defaultCountryCode": "",
  "requesterVatNumber": "",
  "deduplicate": true,
  "includeSyntaxErrors": true,
  "maxConcurrency": 3,
  "maxRetries": 4
}
```

# Actor output Schema

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

No description

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

No description

# 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",
        "DE 811 569 869",
        "IT00000000000",
        "FR123"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("gufobyte/eu-vat-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",
        "DE 811 569 869",
        "IT00000000000",
        "FR123",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("gufobyte/eu-vat-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",
    "DE 811 569 869",
    "IT00000000000",
    "FR123"
  ]
}' |
apify call gufobyte/eu-vat-validator --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,gufobyte/eu-vat-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/QdMDbYLgbmLWywNLA/builds/CjvWX5SWSKkQ7LLy8/openapi.json