# VIES EU VAT Number Scraper (`automation-lab/vies-eu-vat-number-scraper`) Actor Validate EU VAT IDs in bulk via the official VIES API. Export validity, company name, address, status, request ID, and row errors. - **URL**: https://apify.com/automation-lab/vies-eu-vat-number-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 ## VIES EU VAT Number Scraper Validate EU VAT IDs in bulk with the official European Commission VIES REST API. ### What does VIES EU VAT Number Scraper do? This actor checks VAT numbers against the EU VIES service and returns structured validation records. It is designed for batch workflows where a spreadsheet, CRM export, billing list, or KYB queue contains many EU VAT IDs. Each output item contains the normalized VAT ID, validity flag, VIES status, business name, address, request date, request identifier, approximate match details, and per-row error information. ### Who is it for? - ๐Ÿ’ผ B2B sales teams qualifying EU prospects. - ๐Ÿงพ Finance teams validating VAT IDs before invoicing. - ๐Ÿ›’ Ecommerce operators checking B2B tax-exempt orders. - ๐Ÿงช Data teams cleaning CRM and ERP company records. - ๐Ÿ›ก๏ธ KYB and compliance teams enriching counterparty profiles. ### Why use this actor? The VIES website is useful for manual checks, but operational teams often need repeatable bulk validation. This actor turns the official VIES response into export-ready Apify dataset rows. It captures both successful validation fields and failed-row diagnostics, so bad inputs do not stop the whole run. ### Official data source The actor calls the official European Commission VIES REST endpoint. Example source URL pattern: `https://ec.europa.eu/taxation_customs/vies/rest-api/ms/DE/vat/123456789` ### Data you can extract | Field | Description | |---|---| | `input` | Original submitted VAT input. | | `label` | Optional user label copied from object input. | | `countryCode` | Two-letter member-state code used for the check. | | `vatNumber` | VAT number returned or normalized for the request. | | `normalizedVatId` | Country code plus VAT number. | | `isValid` | VIES validity result when available. | | `userError` | VIES status such as INVALID or input error. | | `name` | Company name returned by VIES when available. | | `address` | Registered address returned by VIES when available. | | `requestDate` | VIES request timestamp. | | `requestIdentifier` | VIES request identifier when returned. | | `originalVatNumber` | Original VAT number in the VIES response. | | `approximate` | Approximate-match object from VIES. | | `statusCode` | HTTP status returned by VIES. | | `errorMessage` | Row-level error message if validation failed technically. | | `sourceUrl` | VIES REST URL used for the request. | | `checkedAt` | Actor timestamp for the validation. | ### How much does it cost to validate EU VAT numbers? Pricing uses Apify pay-per-event billing. There is a $0.005 start event for each run and a tiered per-result event for every VAT validation row saved to the dataset. Current per-result prices are: FREE $0.00017441, BRONZE $0.00015166, SILVER $0.00011829, GOLD $0.000090996, PLATINUM $0.000060664, and DIAMOND $0.000042465. Exact live pricing is also shown on the Apify actor page before you start a run. ### Input options The main input is `vatNumbers`. You can provide simple strings: ```json ["DE123456789", "IE6388047V", "FR40303265045"] ```` You can also provide objects: ```json [ { "countryCode": "DE", "vatNumber": "123456789", "label": "Supplier A" }, { "countryCode": "FR", "vatNumber": "40303265045", "label": "Customer B" } ] ``` ### Input parameters - `vatNumbers` โ€” array of VAT strings or VAT objects. - `countryCode` โ€” fallback country code for numbers without a prefix. - `maxItems` โ€” maximum VAT IDs to process from the input array. - `delayMs` โ€” delay between VIES requests. ### Output example ```json { "input": "DE123456789", "countryCode": "DE", "vatNumber": "123456789", "normalizedVatId": "DE123456789", "isValid": false, "userError": "INVALID", "name": null, "address": null, "requestDate": "2026-06-30T03:18:59.799Z", "requestIdentifier": "", "statusCode": 200, "errorMessage": null } ``` ### How to run it 1. Open the actor on Apify. 2. Paste your VAT IDs into the `vatNumbers` field. 3. Set `maxItems` if you want to test only part of a list. 4. Keep the default delay for normal batches. 5. Start the run. 6. Export the dataset as JSON, CSV, Excel, XML, or via API. ### Tips for better results Use country prefixes whenever possible. Remove spaces and punctuation if your source system stores formatted VAT IDs. Use object input with `label` when you need to map results back to internal customer IDs. Keep a modest delay for large batches because VIES is an official public service. ### Error handling Bad rows are returned as dataset items with `userError` and `errorMessage`. A missing country code does not crash the run. A temporary VIES response issue is captured on the affected row. This makes the actor suitable for batch cleaning jobs where some source records are incomplete. ### Integrations Use the actor in Make, Zapier, n8n, Apify API, Google Sheets automation, CRM enrichment pipelines, or data warehouse ingestion jobs. Common workflows include validating leads before sales routing, checking VAT IDs before invoice creation, and refreshing supplier master data. ### 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/vies-eu-vat-number-scraper').call({ vatNumbers: ['DE123456789', 'IE6388047V'], }); console.log(run.defaultDatasetId); ``` ### API usage with Python ```python from apify_client import ApifyClient import os client = ApifyClient(os.environ['APIFY_TOKEN']) run = client.actor('automation-lab/vies-eu-vat-number-scraper').call(run_input={ 'vatNumbers': ['DE123456789', 'IE6388047V'] }) print(run['defaultDatasetId']) ``` ### API usage with cURL ```bash curl -X POST 'https://api.apify.com/v2/acts/automation-lab~vies-eu-vat-number-scraper/runs?token=YOUR_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"vatNumbers":["DE123456789","IE6388047V"]}' ``` ### MCP usage Connect this actor to Apify MCP at: `https://mcp.apify.com/?tools=automation-lab/vies-eu-vat-number-scraper` Claude Code setup: ```bash claude mcp add apify-vies-vat https://mcp.apify.com/?tools=automation-lab/vies-eu-vat-number-scraper ``` MCP JSON configuration: ```json { "mcpServers": { "apify-vies-vat": { "url": "https://mcp.apify.com/?tools=automation-lab/vies-eu-vat-number-scraper" } } } ``` Example prompts: - "Validate these EU VAT numbers and return invalid records only." - "Check whether this supplier VAT ID is valid in VIES." - "Create a CSV-ready table from these VAT validation results." ### Claude Code workflow Use Apify MCP in Claude Code to validate VAT IDs while preparing onboarding scripts, billing checks, or CRM cleanup jobs. Ask Claude to call the actor, inspect the dataset, and summarize invalid records. ### Claude Desktop workflow Add the Apify MCP endpoint in Claude Desktop and request a VIES validation run from a pasted list of VAT IDs. The dataset export can then be downloaded from Apify. ### Legality This actor uses the official EU VIES validation endpoint. Only submit VAT IDs you are allowed to process. Respect applicable privacy, tax, and data-processing rules in your jurisdiction. ### FAQ #### Can I validate VAT IDs from multiple EU countries in one run? Yes. Include the two-letter country prefix in each VAT ID, such as DE, FR, IE, ES, IT, NL, or PL. #### Does the actor use the official VIES source? Yes. It calls the official European Commission VIES REST API and stores the response fields as dataset rows. ### Troubleshooting: VIES returns invalid An `INVALID` status means VIES did not validate that VAT number at the time of the request. Check that the country code is correct and that the number is not formatted with an extra prefix. ### Troubleshooting: missing name or address Some member states may return limited business details. A valid result can still have no public name or address fields. ### Troubleshooting: temporary VIES issues VIES can occasionally return temporary member-state availability errors. Keep failed-row diagnostics and retry affected rows later if the error is not an input problem. ### Related scrapers and tools Explore other automation-lab actors for company enrichment, contact discovery, and compliance data workflows. Use this VAT validator together with CRM enrichment actors when building EU B2B lead pipelines. ### Changelog - Initial version: bulk VAT validation using the official EU VIES REST API. ### Support If a VAT number behaves differently from the VIES website, include the input VAT ID, run ID, and output row in your support request. # Actor input Schema ## `vatNumbers` (type: `array`): EU VAT IDs to check. Use strings like DE123456789, IE6388047V, or FR40303265045. ## `countryCode` (type: `string`): Fallback two-letter EU country code for VAT numbers that do not include a country prefix. ## `maxItems` (type: `integer`): Safety limit for the number of VAT IDs processed from the input array. ## `delayMs` (type: `integer`): Polite delay between requests to the official EU VIES API. Increase for very large batches. ## Actor input object example ```json { "vatNumbers": [ "DE123456789", "IE6388047V", "FR40303265045" ], "countryCode": "DE", "maxItems": 3, "delayMs": 1000 } ``` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "vatNumbers": [ "DE123456789", "IE6388047V", "FR40303265045" ], "countryCode": "DE", "maxItems": 3, "delayMs": 1000 }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/vies-eu-vat-number-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "vatNumbers": [ "DE123456789", "IE6388047V", "FR40303265045", ], "countryCode": "DE", "maxItems": 3, "delayMs": 1000, } # Run the Actor and wait for it to finish run = client.actor("automation-lab/vies-eu-vat-number-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": [ "DE123456789", "IE6388047V", "FR40303265045" ], "countryCode": "DE", "maxItems": 3, "delayMs": 1000 }' | apify call automation-lab/vies-eu-vat-number-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/vies-eu-vat-number-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "VIES EU VAT Number Scraper", "description": "Validate EU VAT IDs in bulk via the official VIES API. Export validity, company name, address, status, request ID, and row errors.", "version": "0.1", "x-build-id": "2Cl04TPh5cwfv6SRj" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~vies-eu-vat-number-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-vies-eu-vat-number-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~vies-eu-vat-number-scraper/runs": { "post": { "operationId": "runs-sync-automation-lab-vies-eu-vat-number-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~vies-eu-vat-number-scraper/run-sync": { "post": { "operationId": "run-sync-automation-lab-vies-eu-vat-number-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", "type": "array", "description": "EU VAT IDs to check. Use strings like DE123456789, IE6388047V, or FR40303265045.", "items": { "type": "string" } }, "countryCode": { "title": "Default country code", "minLength": 2, "maxLength": 2, "type": "string", "description": "Fallback two-letter EU country code for VAT numbers that do not include a country prefix." }, "maxItems": { "title": "Maximum VAT IDs to check", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Safety limit for the number of VAT IDs processed from the input array.", "default": 3 }, "delayMs": { "title": "Delay between VIES requests (ms)", "minimum": 0, "maximum": 10000, "type": "integer", "description": "Polite delay between requests to the official EU VIES API. Increase for very large batches.", "default": 1000 } } }, "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 } } } } } } } } } } ```