# EU VAT Number Validator & VIES Compliance Check API (`gp005/vat-vies-validator`) Actor

Check and validate EU VAT numbers against the official European Commission VIES system — instant valid/invalid status, registered trader name & address, and deregistration-change monitoring for B2B compliance, KYB checks and invoice workflows. Official EC API; no login, no scraping, pay per lookup.

- **URL**: https://apify.com/gp005/vat-vies-validator.md
- **Developed by:** [Geo](https://apify.com/gp005) (community)
- **Categories:** Developer tools, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.00 / 1,000 vat validateds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## EU VAT Number Validator & VIES Compliance Check API

**What is the EU VAT Number Validator?** An [Apify](https://apify.com) API that checks EU VAT numbers against the **official European Commission VIES system** — the same database tax authorities and EU institutions use. Give it a VAT number (or a list), and it returns `valid` true/false plus the registered trader name and address, straight from the official EC endpoint. No login, no scraping, no third-party databases.

Built for **B2B compliance workflows**: vendor KYB (know-your-business) checks, invoice verification before payment, and ongoing **deregistration monitoring** — detect when a supplier's VAT number stops being valid before your next invoice is rejected.

### What can this Actor do?

- ✅ **Validate VAT numbers** for all 27 EU member states plus Northern Ireland (`XI`) against the official VIES database
- ✅ **Return trader details** — registered company name, street, postal code, city, and company type
- ✅ **Monitor for changes** — re-run on a schedule and get a `statusChanged: true` flag (plus previous values) when a number flips valid↔invalid or the registered details change
- ✅ **Cache lookups** — server-side cache with a configurable TTL (default 24h) so repeated checks of the same number are cheaper and lighter on the EU service
- ✅ **Concurrency control** — set 1–5 parallel requests to stay polite to the official EC service

| Field | What it contains |
|---|---|
| `countryCode` | 2-letter EU country prefix (`DE`, `FR`, `IE`, …) |
| `vatNumber` | Normalized full VAT number |
| `valid` | `true` / `false` from the official VIES database |
| `name`, `address` | Registered trader name and address |
| `traderCity`, `traderCompanyType` | Registered city and company type |
| `source` | `fresh` (VIES lookup), `cache` (within TTL), or `soap` (fallback) |
| `statusChanged` | `true` when monitor mode detected a change vs. the previous run |
| `previousValid` | Previous validity status (monitor mode) |
| `cachedAt` | When the cached result was first stored (cache hits) |
| `status` / `reason` | `ok`, or `error` + the reason (malformed numbers, unsupported country, VIES unreachable) |

### Why use the official VIES API?

The European Commission's [VIES (VAT Information Exchange System)](https://ec.europa.eu/taxation_customs/vies/) is the authoritative source for EU VAT registration status. This Actor calls the **official EC REST API** (with a SOAP fallback) — the same data source national tax authorities use. There is no login wall, no API key to manage, and the data comes from the EU's own public service, not a reseller or scraper.

### When to check EU VAT numbers

- **Vendor onboarding (KYB)** — confirm a new supplier's VAT registration before they enter your payables system
- **Invoice verification** — check the seller's VAT number on every incoming invoice before payment
- **Deregistration monitoring** — scheduled re-checks that flag the moment a counterparty's VAT number stops being valid or their registered details change
- **One-off due diligence** — a quick `valid` true/false before a contract or a cross-border transaction

### How to validate EU VAT numbers with the VIES API

1. Open the Actor page and click **Try for free** (or **Start** in Console).
2. In the input, paste the VAT numbers you want to check — each with its 2-letter country prefix:
   ```json
   {
     "vatNumbers": ["IE8256796U", "DE123456789", "FR12345678901"]
   }
   ```
   Spaces, dots and dashes are ignored: `IE 8256796U` works the same as `IE8256796U`.
3. Run it. Each number becomes one dataset row with `valid`, trader `name`, and `address`.
4. Export results as JSON, CSV, Excel, or HTML, or fetch them over the **API tab** (REST endpoint with your API token).

#### How to monitor VAT numbers for deregistration

1. Set `monitorChanges: true` in the input.
2. Schedule the Actor to run **daily** (or weekly) via the **Scheduling tab** — no code needed.
3. Each run compares fresh VIES results against the stored snapshot. If a supplier's number flips from valid to invalid — or their registered name/address changes — the dataset row carries `statusChanged: true` with the previous values.
4. Point a webhook, Make, or n8n at the run to alert your team the moment a counterparty's VAT status changes.

### Pricing — pay per event

This Actor uses Apify's **pay-per-event** model — you only pay for what you use, no monthly subscription:

| Event | Price |
|---|---|
| `actor-start` (per run) | $0.005 |
| `vat-validated` (per fresh VIES lookup) | $0.004 |
| `vat-cache-hit` (per cached lookup within TTL) | $0.001 |
| `vat-status-changed` (monitor mode, per detected change) | $0.02 |

**Worked example:** checking 10 supplier VAT numbers on a fresh run costs `$0.005 + 10 × $0.004 = $0.045`. Re-running the same 10 within the cache TTL costs `$0.005 + 10 × $0.001 = $0.015`. A weekly monitor of 50 vendors that detects one deregistration costs `$0.005 + 50 × $0.004 + $0.02 = $0.225`.

Apify's free plan includes platform credits — most first runs are free. Full pricing details on the **Pricing tab**.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `vatNumbers` | array of strings | **required** | Full VAT numbers with 2-letter country prefix, e.g. `["IE8256796U", "DE123456789"]` |
| `monitorChanges` | boolean | `false` | Store snapshots and flag `statusChanged` when validity or trader details change between runs |
| `cacheTtlHours` | integer | `24` | How long to serve repeat lookups from cache. `0` = always fresh. Monitor mode always looks up fresh. |
| `maxConcurrency` | integer | `2` | Max parallel VIES requests (1–5). Keep low to stay polite to the official EC service. |

### Output — example

```json
{
  "countryCode": "IE",
  "vatNumber": "IE8256796U",
  "valid": true,
  "requestDate": "2026-09-01T09:00:00.000Z",
  "name": "MICROSOFT IRELAND OPERATIONS LIMITED",
  "address": "ONE MICROSOFT PLACE, SOUTH COUNTY BUSINESS PARK, LEOPARDSTOWN, DUBLIN 18",
  "traderCity": "DUBLIN",
  "source": "fresh",
  "statusChanged": false,
  "previousValid": null,
  "status": "ok",
  "timestamp": "2026-09-01T09:00:00.000Z"
}
```

Invalid or unregistered numbers return `valid: false` with `---` in the trader fields — a deterministic, complete result either way.

### Integrations

- **API** — call this Actor from any REST client via the API tab (`https://api.apify.com/v2/acts/gp005~vat-vies-validator/runs`). Perfect for scripting into invoicing or ERP flows.
- **MCP** — like all Apify Actors, it's callable from AI agents via the Apify MCP server.
- **Webhooks** — subscribe to run events to trigger downstream alerting.
- **Make / n8n / Zapier** — Apify's HTTP API integrates with every major automation platform.
- **Scheduling** — run daily/weekly on the platform with zero infrastructure.

### Other useful Actors from the same developer

- [SSL/TLS Certificate Expiry Monitor](https://apify.com/gp005/tls-cert-monitor) — the same monitor-on-a-schedule pattern for TLS certificates
- [EDGAR Company Filings & XBRL Fundamentals Extractor](https://apify.com/gp005/edgar-xbrl-fundamentals) — company financial fundamentals from SEC filings
- [Sanctions Screening API — GLEIF LEI & OFAC/EU/UN/UK Checker](https://apify.com/gp005/gleif-sanctions-screener) — counterparty screening against GLEIF LEI and the major sanctions lists
- [Office-to-PDF & Universal Document Converter](https://apify.com/gp005/office-to-pdf) — convert Word/Excel/PPT to PDF in one run

### FAQ

#### Is VIES data up to date?

VIES is maintained in near-real-time by EU member states' tax authorities. There is a small lag between a registration/deregistration being processed nationally and appearing in VIES — treat a result as current, but confirm with the national authority for legally binding decisions.

#### What happens if the VAT number format is wrong?

The Actor validates the format and country code up front. Malformed numbers are skipped with a structured error row (`status: "error"` + reason) — you never pay for a VIES lookup that can't be done.

#### Does this cover UK (GB) VAT numbers?

No — the UK left VIES after Brexit. Only EU member states plus Northern Ireland (`XI`) are supported. Non-EU numbers return an error row explaining the unsupported country code.

#### What is the trader name/address used for?

The registered name and address are the official trader details returned per-query by VIES — exactly what you need for KYB checks and invoice matching. They are returned per lookup, not collected into any index.

#### Is the VIES API free?

The European Commission's VIES service itself is free and public — there is no EC API key or subscription. This Actor charges per event because it turns that raw service into a repeatable API: caching, concurrency control, monitoring snapshots, structured JSON output, and no-rate-limit handling — so you pay for the run, not for VIES access.

#### Can I look up a VAT number by company name?

No. VIES only accepts a full VAT number (country prefix + digits) — there is no reverse lookup by company name. This Actor returns the registered company name and address **for a given VAT number**, which is exactly what invoice-matching and KYB checks need.

#### Why did my validation fail with invalid\_input?

The Actor validates the format and country code before any VIES call. A malformed number (wrong length, bad check digits, unsupported country) is skipped and returned as a structured error row (`status: "error"` + `reason`) — you are never charged a validation event for a lookup that couldn't be performed.

#### What happens when VIES is down?

The Actor falls back to the official SOAP endpoint when the REST API fails. If both endpoints are unreachable, each number returns a structured error row and no validation event is charged — no silent failures, no false `valid: false` results.

#### Is this a legal confirmation service?

No. The Actor is a preflight verification tool using the official VIES database. For legally binding decisions, confirm with the relevant national tax authority.

### Limitations

- **VIES coverage** — only EU member states plus Northern Ireland (`XI`) are supported. The UK (`GB`) is not in VIES since Brexit; `GB` numbers return a structured error row.
- **Freshness** — VIES reflects what member states' tax authorities have registered; there is a short national-processing lag before a deregistration appears.
- **Trader details** — VIES returns the registered name/address only when the member state provides them; some return `---` placeholders even for valid numbers.
- **Official-service dependency** — the Actor calls the EU's public VIES service and honors its fair-use guidance (concurrency limited to 1–5, server-side cache). Under EC outages, the SOAP fallback is used; if both endpoints fail, structured error rows are returned and no validation event is charged.
- **Not legal advice** — output is for preflight compliance workflows, not a certification or legal opinion.

#### I have a custom use case

Open the **Issues tab** — feedback is welcome, and custom solutions are available.

### Support

- Found a bug or want a feature? Open an issue on the **Issues tab**.
- Questions about billing or platform features → Apify's docs and support.

# Actor input Schema

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

List of full EU VAT numbers to validate against the official European Commission VIES system, each with its 2-letter country code prefix. Spaces, dots and dashes are ignored (e.g. "IE 8256796U", "DE123456789", "FR-12345678901"). Returns valid/invalid status plus registered trader name and address.

## `monitorChanges` (type: `boolean`):

When enabled, the actor stores a snapshot of each lookup result (valid status, trader name, address) in its key-value store and compares it on every re-run. A VAT number that flips from valid to invalid (deregistered), or whose trader details change, produces a status-changed record and a 'vat-status-changed' charge event. Schedule the actor on a cron and use the 'statusChanged' field as your alert trigger.

## `cacheTtlHours` (type: `integer`):

How long (in hours) to serve repeat lookups for the SAME VAT number from the actor's internal cache instead of calling VIES again — reduces load on the EU service and lowers your cost (cached results are charged at the reduced cache-hit rate). 0 disables caching (always a fresh VIES lookup). Monitor mode always forces a fresh lookup so deregistration is never masked by the cache.

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

Maximum concurrent requests to the European Commission VIES service. Keep at 1-2 to stay polite to the official EC service and avoid rate limits; raise to 5 only for large batch validation runs.

## Actor input object example

```json
{
  "vatNumbers": [
    "IE8256796U",
    "DE123456789"
  ],
  "monitorChanges": true,
  "cacheTtlHours": 24,
  "maxConcurrency": 2
}
```

# Actor output Schema

## `dataset` (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": [
        "IE8256796U",
        "DE123456789"
    ],
    "monitorChanges": false,
    "cacheTtlHours": 24,
    "maxConcurrency": 2
};

// Run the Actor and wait for it to finish
const run = await client.actor("gp005/vat-vies-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": [
        "IE8256796U",
        "DE123456789",
    ],
    "monitorChanges": False,
    "cacheTtlHours": 24,
    "maxConcurrency": 2,
}

# Run the Actor and wait for it to finish
run = client.actor("gp005/vat-vies-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": [
    "IE8256796U",
    "DE123456789"
  ],
  "monitorChanges": false,
  "cacheTtlHours": 24,
  "maxConcurrency": 2
}' |
apify call gp005/vat-vies-validator --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,gp005/vat-vies-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/N1i4QgIsAxzFE9rQr/builds/76wAfVGdAAgyqBcOp/openapi.json