# EU VIES VAT Validation Batch (`jpmarketdata/eu-vies-vat-validation-batch`) Actor

Check up to 20 customer VAT IDs against the official EU VIES service and get a private, timestamped valid/invalid reconciliation list.

- **URL**: https://apify.com/jpmarketdata/eu-vies-vat-validation-batch.md
- **Developed by:** [h ichi](https://apify.com/jpmarketdata) (community)
- **Categories:** Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 94.1% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.50 / 1,000 vies vat status resolveds

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?

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 VIES VAT Validation Batch

Check 1–20 customer VAT IDs against the European Commission's official VIES service. Use this for scheduled B2B onboarding and invoice-list reconciliation. It returns current valid/invalid answers with source and observation times. It does not establish customer identity, a tax exemption, historical status or a consultation-number certificate.

### Input

Provide unique full EU VAT IDs with a two-letter member-state prefix. The default is two publicly posted corporate IDs, IE6388047V and DE129274202; an empty object uses this default. Explicit empty arrays, duplicates, unsupported prefixes and malformed IDs fail before any source request. The buyer's list may contain private identifiers; do not add names or addresses.

### Output

One row per input, preserving input order. `inputIndex` lets the buyer join privately to the original list; only a masked suffix is displayed. The mask shows country prefix, ellipsis and at most the last three national-number characters, always hiding at least one national-number character. `status=VALID` or `INVALID` maps exactly to VIES `valid=true/false`, with source request date and UTC observation time. False can mean no registration, no intra-EU activation, or unfinished registration; consult the relevant tax authority for a disputed result. No name, address, full VAT number, request identifier or raw VIES response is emitted. The European Commission is the source and does not endorse this Actor.

### Price

$0.0015 for each delivered, definitive VAT row via one `vat-validation-resolved` primary PPE event, no start or secondary charge. Both valid and invalid answers count. Maximum 20 IDs/$0.03. An unavailable VIES service or malformed input creates no dataset rows or primary events.

### Limits and failure behavior

Official anonymous VIES REST JSON POST only; 256 MB, direct egress, at most one robots GET and 20 sequential VAT POSTs, 2-second spacing, 15-second per-request timeout, 120-second run budget and 2 MiB maximum per response. Validate every response before pushing any dataset row or charging. On 400/401/403/429/5xx, timeout, member-state unavailable, robots disallow, response mismatch or missing definitive answer, fail the entire run uncharged and without logging VAT IDs. Do not turn an outage into INVALID, retry aggressively, scrape the UI, or guarantee the source is uninterrupted.

### Privacy and rights

Only buyer-provided IDs are queried. The source response's trader name, address and any consultation/request identifier are discarded. Dataset masks the ID and buyer joins using the input position. Cite the official European Commission endpoint, attribute the source and do not imply official endorsement.

# Actor input Schema

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

One to 20 unique exact EU VAT IDs, each with its two-letter member-state prefix. The default contains two publicly posted corporate IDs. IDs may belong to sole traders: avoid putting personal names in input.

## Actor input object example

```json
{
  "vatNumbers": [
    "IE6388047V",
    "DE129274202"
  ]
}
```

# Actor output Schema

## `results` (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",
        "DE129274202"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("jpmarketdata/eu-vies-vat-validation-batch").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",
        "DE129274202",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("jpmarketdata/eu-vies-vat-validation-batch").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",
    "DE129274202"
  ]
}' |
apify call jpmarketdata/eu-vies-vat-validation-batch --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,jpmarketdata/eu-vies-vat-validation-batch"
        }
    }
}
```

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/P10SKRXb5IeBcjeex/builds/w8x5XsnJ2wA0OUZEF/openapi.json