EU VIES VAT & Company Registry Bulk Verifier — Self-Healing Apify Actor & MCP Server (eu-vies-vat-bulk-validator-mcp)

{
  "id": "vies:IE6388047V",
  "normalized_vat": "IE6388047V",
  "syntax_valid": true,
  "valid": true,
  "company_name": "GOOGLE IRELAND LIMITED",
  "parsed_address": {
    "street": "1ST & 2ND FLOOR, GORDON HOUSE, BARROW STREET",
    "postal_code": "DUBLIN 4",
    "city": "DUBLIN 4"
  },
  "consultation_number": "WAPIAAAAZ1B2C3D4",
  "healing_tiers": {"vies_lookup": "tier1_rest_json"},
  "ppe_event": "item_scraped"
}

Keywords: eu-vies-vat-validator, vies-rest-soap-api, eu-reverse-charge-kyb, apify-mcp-server, bulk-vat-number-check

---

Why FinOps, ERP & Tax Compliance Teams Use This Actor (ROI vs. DIY)

When invoicing B2B customers across the European Union under the EU VAT Reverse-Charge mechanism (Article 196 of Directive 2006/112/EC), finance teams must verify that every buyer's VAT identification number is actively valid in the European Commission VIES registry and retain the registered company name, address, and consultation identifier (requestIdentifier) for tax audit defense.

Approach	Setup & Maintenance Effort	Member State Outage Resilience	MCP / AI Agent Ready	Cost Structure
In-House Script (DIY)	16–24 hrs (REST + SOAP 1.1 XML parser + 28 regexes)	Breaks when REST gateway returns 503 or MS_UNAVAILABLE	Manual wrapper required	€800+ engineering setup
Enterprise KYB Platforms	Annual procurement & sales onboarding	High	Proprietary REST API	€400–€1,500/mo minimum
This Actor (eu-vies-vat-bulk-validator-mcp)	0 hrs (Instant Apify API, CLI, or MCP)	3-Tier Self-Healing (Pre-flight Regex + REST + SOAP 1.1 Fallback)	Native JSON & MCP Schema	Pay-Per-Event (item_scraped)

---

30-Second Copy-Paste Quickstart

Validate a batch of EU + Northern Ireland (XI) VAT numbers directly from the CLI:

$python3 workspaces/actors/eu-vies-vat-bulk-validator-mcp/main.py --vat "IE6388047V,SE556703748501,GR094014201"

Or run with an explicit JSON configuration payload (including optional requester VAT for official VIES consultation numbers):

$python3 workspaces/actors/eu-vies-vat-bulk-validator-mcp/main.py --input-json '{"vatNumbers":["IE6388047V","SE556703748501"],"requesterCountryCode":"DE","requesterVatNumber":"DE123456789"}'

Run the zero-dependency unit and self-healing regression test suite:

$python3 -m unittest discover -s workspaces/actors/eu-vies-vat-bulk-validator-mcp -p "test_*.py" -v

---

3-Tier Self-Healing VIES Verification Architecture

1. Pre-Flight Normalization & 28-State Syntax Guard (normalize_and_validate_vat_syntax):
   • Strips spaces, dots, slashes, and hyphens from messy ERP/CRM exports.
   • Automatically maps Greece's ISO-3166 alpha-2 prefix (GR) to its mandatory VIES prefix (EL), and normalizes 9-digit Belgian numbers to 10-digit leading-zero format.
   • Validates against official regular expressions for all 27 EU Member States (AT, BE, BG, CY, CZ, DE, DK, EE, EL, ES, FI, FR, HR, HU, IE, IT, LT, LU, LV, MT, NL, PL, PT, RO, SE, SI, SK) plus Northern Ireland (XI).
   • Invalid syntax is rejected locally (ppe_event: "syntax_rejected") in <1ms without wasting VIES rate limits or billing events.
2. Tier 1 Primary — Official EC VIES REST API:
   • Queries POST https://ec.europa.eu/taxation_customs/vies/rest-api/check-vat-number with exponential backoff on transient Member State concurrency limits (MS_MAX_CONCURRENT_REQ, MS_UNAVAILABLE).
3. Tier 2 Fallback — Official EC VIES SOAP 1.1 XML Endpoint:
   • If the VIES REST gateway returns HTTP 5xx or an unparseable response, the Actor automatically constructs a standards-compliant SOAP 1.1 <urn:checkVat> (or <urn:checkVatApprox>) XML envelope and queries POST https://ec.europa.eu/taxation_customs/vies/services/checkVatService.
4. Structured European Address Parser (parse_vies_address):
   • Splits multi-line VIES registry addresses into structured street, postal_code, city, and raw_address fields across continental, Irish, and Nordic postal formats.

---

Input & Output Schema Reference

Input Parameters (INPUT_SCHEMA.json)

• vatNumbers (array of strings, required): List of EU or XI VAT numbers to verify (e.g. ["IE6388047V", "SE556703748501"]).
• requesterCountryCode (string, optional): Two-letter VIES country code of your company to request an official consultation number (requestIdentifier).
• requesterVatNumber (string, optional): Your company's VAT number for checkVatApprox audit trail generation.
• maxRetries (integer, optional, default 3): Maximum retry attempts per tier on transient Member State unavailability.

Output Record Fields

• id: Canonical identifier (vies:<country_code><vat_number>).
• vat_input: Raw input string supplied by the caller.
• country_code: Normalized 2-letter VIES jurisdiction code (AT..SK, EL, XI).
• vat_number: Normalized numeric/alphanumeric VAT body without prefix.
• normalized_vat: Combined canonical VAT number (<country_code><vat_number>).
• syntax_valid: Boolean indicating whether the number passed 28-prefix pre-flight regex validation.
• valid: Official VIES registry active status (true / false).
• company_name: Registered legal entity name returned by the national tax authority.
• address: Raw multi-line address returned by VIES.
• parsed_address: Structured object containing street, postal_code, city, and raw_address.
• request_date: Official timestamp of the VIES verification.
• consultation_number: Official VIES requestIdentifier when requester credentials are provided.
• healing_tiers: Audit map showing which tier (tier1_rest_json, tier2_soap_xml, or preflight_syntax_guard) resolved the query.
• ppe_event: "item_scraped" for verified records or "syntax_rejected" for malformed inputs.

---

Scope & Compatibility (What's Included / What's Not Included)

• What's Included:
  • Zero-dependency Python 3.9+ Apify Actor (main.py) with 28-jurisdiction EU/XI regex pre-flight validation, official EC VIES REST Tier 1 client, and SOAP 1.1 XML Tier 2 fallback.
  • Structured multi-line European address parser (street, postal_code, city).
  • Apify Cloud Key-Value Store input loader, Dataset item pusher, Dockerfile, .actor/actor.json, and automated unit test suite (test_actor.py).
• What's Not Included (Anti-Refund Warranty Boundary):
  • Does not override national tax authority databases that do not publicly disclose trader names/addresses via VIES (e.g., German DE or Spanish ES VIES endpoints return valid: true/false without trader name/address unless queried through national portals).
  • Does not verify non-EU VAT/GST numbers outside the 27 EU Member States + Northern Ireland (XI) (e.g., Great Britain GB, Switzerland CHE, Norway NO are not part of the EC VIES system and are rejected at the pre-flight syntax stage).
  • Does not constitute formal legal or tax advisory services; provided as an automated B2B data verification utility.