# EU VIES VAT Registry Scraper (`automation-lab/eu-vies-vat-registry-scraper`) Actor

Validate EU VAT numbers in bulk with the official VIES registry. Export validity, company details, request dates, and per-row faults.

- **URL**: https://apify.com/automation-lab/eu-vies-vat-registry-scraper.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use 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 VIES VAT Registry Scraper

Validate EU VAT numbers in bulk with the official VIES registry and export audit-ready validity snapshots.

### What does EU VIES VAT Registry Scraper do?

EU VIES VAT Registry Scraper checks VAT numbers against the European Commission VIES service.
It accepts a batch of VAT identifiers.
It normalizes country codes and VAT numbers.
It returns whether each VAT number is valid.
It includes the VIES request date.
It includes company name and address when the member-state service returns them.
It records per-row errors instead of failing an entire batch.

### Who is it for?

Finance teams use it to validate customers before invoicing.
Compliance teams use it to keep VAT audit snapshots.
Marketplace operators use it to verify seller VAT details.
RevOps teams use it to clean CRM account data.
Procurement teams use it to check vendor VAT numbers.
Accountants use it for EU cross-border transaction checks.

### Why use this actor?

✅ Uses the official public EU VIES endpoint.
✅ No account, cookies, browser, or private API key required.
✅ Batch-friendly input for spreadsheet and CRM exports.
✅ Per-record fault fields make intermittent member-state outages visible.
✅ Output is structured for CSV, JSON, Excel, and API workflows.

### What data can you extract?

| Field | Description |
| --- | --- |
| `input` | Original submitted VAT value. |
| `countryCode` | Normalized VIES country code. |
| `vatNumber` | VAT number without country prefix. |
| `normalizedVat` | Combined country and VAT number. |
| `valid` | Boolean validity result from VIES. |
| `requestDate` | Date returned by VIES. |
| `companyName` | Company name when available. |
| `companyAddress` | Company address when available. |
| `checkedAt` | Timestamp for the actor check. |
| `errorType` | Per-record issue category. |
| `errorMessage` | Human-readable per-record error. |

### How much does it cost to validate EU VAT numbers?

The actor uses pay-per-event pricing.
There is a small start fee per run.
Each VAT validation row is charged as one result event.
Use `maxItems` for a cheap sample run before processing a larger list.
Bulk runs are usually inexpensive because the actor uses direct HTTP requests and no browser.

### Input

The main input is `vatNumbers`.
You can provide strings with a country prefix.
You can also provide objects with `countryCode` and `vatNumber`.
Examples:

```json
{
  "vatNumbers": ["IE6388047V", "DE123456789", "FR40303265045"],
  "maxItems": 100,
  "maxConcurrency": 3,
  "maxRetries": 2
}
````

### Output

Each submitted VAT number becomes one dataset row.
Valid numbers include returned company fields when VIES exposes them.
Invalid numbers still produce a row with `valid=false`.
Faults and unsupported inputs include error fields.
This makes reconciliation easy because output row count matches processed input count.

### How to use the actor

1. Prepare a list of EU VAT numbers.
2. Open the actor on Apify.
3. Paste the list into `vatNumbers`.
4. Keep the default concurrency for a safe first run.
5. Start the actor.
6. Download results as CSV, JSON, Excel, or via API.

### Tips for reliable VIES checks

Use country prefixes such as `IE`, `DE`, `FR`, or `NL`.
Remove spaces and punctuation if your source file is inconsistent.
Keep `maxConcurrency` modest for very large batches.
Retry later if a member-state system returns `MS_UNAVAILABLE`.
Store `checkedAt` and `requestDate` for audit history.

### Supported countries

The actor supports VIES member-state country codes.
It also accepts `XI` for Northern Ireland VAT checks where VIES supports it.
Unsupported country prefixes are returned as per-record errors.
They do not stop the run.

### VIES availability caveat

VIES depends on national member-state databases.
A single member state can be temporarily unavailable.
The actor retries transient faults lightly.
If a fault remains, the row includes `faultCode`, `faultString`, and `errorMessage`.
This is preferable to hiding operational uncertainty.

### Integrations

Connect the actor to Google Sheets with Apify integrations.
Trigger it from Zapier when a new B2B lead is added.
Run it from Make.com for vendor onboarding checks.
Call it from your CRM enrichment workflow.
Export dataset rows to your data warehouse.
Schedule periodic revalidation of customer VAT records.

### API usage with Node.js

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/eu-vies-vat-registry-scraper').call({
  vatNumbers: ['IE6388047V', 'FR40303265045'],
  maxItems: 100
});
console.log(run.defaultDatasetId);
```

### API usage with Python

```python
from apify_client import ApifyClient

client = ApifyClient('YOUR_APIFY_TOKEN')
run = client.actor('automation-lab/eu-vies-vat-registry-scraper').call(run_input={
    'vatNumbers': ['IE6388047V', 'FR40303265045'],
    'maxItems': 100,
})
print(run['defaultDatasetId'])
```

### API usage with cURL

```bash
curl -X POST "https://api.apify.com/v2/acts/automation-lab~eu-vies-vat-registry-scraper/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vatNumbers":["IE6388047V","FR40303265045"],"maxItems":100}'
```

### MCP usage

Use Apify MCP to run the actor from Claude Desktop or Claude Code.
MCP server URL:

```text
https://mcp.apify.com/?tools=automation-lab/eu-vies-vat-registry-scraper
```

Claude Code setup:

```bash
claude mcp add apify-vies-vat https://mcp.apify.com/?tools=automation-lab/eu-vies-vat-registry-scraper
```

Claude Desktop JSON config:

```json
{
  "mcpServers": {
    "apify-vies-vat": {
      "url": "https://mcp.apify.com/?tools=automation-lab/eu-vies-vat-registry-scraper"
    }
  }
}
```

Example prompts:

- Validate these EU VAT numbers and summarize invalid records.
- Check whether my vendor VAT spreadsheet contains unsupported country codes.
- Run a VIES validation batch and return rows with company names.

### Example workflows

#### Customer onboarding

Validate a VAT number when a customer submits a billing form.
Save `valid`, `companyName`, and `checkedAt` into your account record.

#### Vendor master cleanup

Export vendor VAT numbers from ERP.
Run the actor in batches.
Merge normalized VAT and validity status back into the vendor table.

#### Periodic compliance monitoring

Schedule a monthly run for active EU customers.
Compare current validity against historical snapshots.
Investigate records that changed from valid to invalid.

### Troubleshooting

#### Why is a valid VAT missing a name or address?

Some member states suppress name or address in VIES responses.
The validity flag can still be useful even when company fields are empty.

#### Why did I get `MS_UNAVAILABLE`?

That fault means a national member-state service was unavailable.
Try again later or reduce concurrency.
The actor records the fault on the row so the batch remains usable.

#### Why did an input return `INVALID_INPUT`?

The actor could not split the value into a two-letter country code and VAT number.
Use formats such as `IE6388047V` or `{ "countryCode": "IE", "vatNumber": "6388047V" }`.

### Data freshness

VIES returns a validation snapshot at request time.
Use `requestDate` and `checkedAt` to prove when the check occurred.
Repeat runs if your compliance policy requires recurring validation.

### Legality

The actor queries the official public VIES VAT validation service.
You are responsible for using the results in line with applicable laws, platform terms, and your compliance obligations.
Do not submit personal data that is unrelated to VAT validation.

### Related scrapers

- https://apify.com/automation-lab/france-sirene-company-scraper
- https://apify.com/automation-lab/zefix-swiss-company-registry-scraper
- https://apify.com/automation-lab/ofac-sanctions-list-export-scraper
- https://apify.com/automation-lab/sec-company-facts-api-scraper

### FAQ

#### Does this actor use a browser?

No. It uses direct HTTP SOAP requests to VIES.

#### Does it require proxies?

No. The official endpoint is public and was reachable directly during implementation.

#### Can I upload thousands of VAT numbers?

Yes, up to the input limit. For very large files, start with a smaller sample to verify formatting.

#### Does it enrich every company name and address?

Only when VIES/member-state systems return those fields.
Some countries return validity without detailed company information.

#### Can one bad VAT number fail the run?

No. Bad inputs and VIES faults are emitted as result rows with error fields.

### Changelog

Initial version validates batches through the VIES `checkVat` SOAP endpoint and exports audit-friendly result rows.

# Actor input Schema

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

EU VAT numbers with country prefix (for example IE6388047V, DE123456789) or objects with countryCode and vatNumber.

## `maxItems` (type: `integer`):

Caps how many VAT numbers are processed from the input list. Useful for testing a small sample before a large batch.

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

Parallel requests to the official VIES SOAP endpoint. Keep low because member-state services can be intermittent.

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

Light retry count for transient VIES/member-state faults such as SERVICE\_UNAVAILABLE or MS\_UNAVAILABLE.

## Actor input object example

```json
{
  "vatNumbers": [
    "IE6388047V",
    "DE123456789",
    "FR40303265045"
  ],
  "maxItems": 20,
  "maxConcurrency": 3,
  "maxRetries": 2
}
```

# Actor output Schema

## `overview` (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",
        "DE123456789",
        "FR40303265045"
    ],
    "maxItems": 20,
    "maxConcurrency": 3,
    "maxRetries": 2
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/eu-vies-vat-registry-scraper").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",
        "DE123456789",
        "FR40303265045",
    ],
    "maxItems": 20,
    "maxConcurrency": 3,
    "maxRetries": 2,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/eu-vies-vat-registry-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).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",
    "DE123456789",
    "FR40303265045"
  ],
  "maxItems": 20,
  "maxConcurrency": 3,
  "maxRetries": 2
}' |
apify call automation-lab/eu-vies-vat-registry-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=automation-lab/eu-vies-vat-registry-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "EU VIES VAT Registry Scraper",
        "description": "Validate EU VAT numbers in bulk with the official VIES registry. Export validity, company details, request dates, and per-row faults.",
        "version": "0.1",
        "x-build-id": "HuJmYvsAsqRYGJu4P"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/automation-lab~eu-vies-vat-registry-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-automation-lab-eu-vies-vat-registry-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/automation-lab~eu-vies-vat-registry-scraper/runs": {
            "post": {
                "operationId": "runs-sync-automation-lab-eu-vies-vat-registry-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/automation-lab~eu-vies-vat-registry-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-automation-lab-eu-vies-vat-registry-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "vatNumbers"
                ],
                "properties": {
                    "vatNumbers": {
                        "title": "VAT numbers",
                        "minItems": 1,
                        "maxItems": 10000,
                        "type": "array",
                        "description": "EU VAT numbers with country prefix (for example IE6388047V, DE123456789) or objects with countryCode and vatNumber.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "maxItems": {
                        "title": "Maximum VAT numbers to process",
                        "minimum": 1,
                        "maximum": 10000,
                        "type": "integer",
                        "description": "Caps how many VAT numbers are processed from the input list. Useful for testing a small sample before a large batch.",
                        "default": 20
                    },
                    "maxConcurrency": {
                        "title": "Maximum parallel VIES requests",
                        "minimum": 1,
                        "maximum": 10,
                        "type": "integer",
                        "description": "Parallel requests to the official VIES SOAP endpoint. Keep low because member-state services can be intermittent.",
                        "default": 3
                    },
                    "maxRetries": {
                        "title": "Retries per VAT number",
                        "minimum": 0,
                        "maximum": 5,
                        "type": "integer",
                        "description": "Light retry count for transient VIES/member-state faults such as SERVICE_UNAVAILABLE or MS_UNAVAILABLE.",
                        "default": 2
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```