Bulk VAT Validation

POST /v1/vat/bulk validates up to 100 EU VAT numbers in a single API call. Each ID runs through the same VIES + national-fallback pipeline as GET /v1/vat/:vatId, so results are identical — you just get them all back together, as one result per VAT ID plus a summary of how many were valid, invalid, or errored. One bad or unreachable VAT ID never fails the rest of the batch: the response is always 200 OK.

When to Use It

• Cleaning an imported customer or supplier list before it hits your billing system
• Periodic re-validation of VAT numbers you already store, in scheduled batches
• Pulling a fresh, timestamped result set together ahead of a VAT audit

For a single VAT ID looked up on demand — at checkout, on account creation — use GET /v1/vat/:vatId instead; it also returns company name, address and other enrichment fields that the bulk endpoint omits.

Endpoint

POST /v1/vat/bulk

Requires a live API key, the same as every other billable endpoint — see Authentication.

Request

Body

No query parameters. The requester VAT used for consultation numbers comes entirely from your account-level dashboard Settings and applies to the whole batch— every item that reaches VIES directly returns a consultation number once it's set.

curl https://api.vatnode.dev/v1/vat/bulk \
  -H "Authorization: Bearer vat_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "vatIds": ["IE6388047V", "DE143454214", "DE12345"]
  }'

Response

Always 200 OK — a request-level failure (auth, malformed body) is the only thing that returns a non-200 status. Per-item outcomes live in results.

{
  "results": [
    {
      "vatId": "IE6388047V",
      "valid": true,
      "source": "VIES",
      "consultationNumber": null
    },
    {
      "vatId": "DE143454214",
      "valid": true,
      "source": "CACHE",
      "consultationNumber": null
    },
    {
      "vatId": "DE12345",
      "valid": null,
      "source": null,
      "consultationNumber": null,
      "error": {
        "code": "INVALID_FORMAT",
        "message": "Invalid VAT ID format. Expected format: country code (2 letters) followed by VAT number"
      }
    }
  ],
  "summary": {
    "requested": 3,
    "valid": 2,
    "invalid": 0,
    "errors": 1
  }
}

Response Fields

Billing & Quota

Anything that comes back with an error field costs nothing — it either never touched your quota or the reservation was refunded. In practice that covers:

• Malformed VAT IDs (INVALID_FORMAT) — rejected before any quota is reserved.
• Upstream failures — VIES or a national fallback being unreachable (VIES_UNAVAILABLE, UPSTREAM_TIMEOUT), an invalid requester (INVALID_REQUESTER), or any other unexpected error — the reservation for that item is refunded.
• Quota-exceeded items (RATE_LIMITED) — by definition never reserved a slot in the first place.

Duplicate VAT IDs within the same request are de-duplicated before processing, so listing the same VAT ID twice produces one result and is billed once — not twice.

Behavior Notes

• De-duplication. Repeated VAT IDs in vatIds are collapsed to one entry, first-seen order preserved.
• A requester bypasses the cache. When your account has a requester VAT configured in dashboard Settings, every item is checked live against VIES so it can carry a fresh consultation number tied to that requester — a cached result never carries one. This also means national-fallback recovery is skipped in this mode, same as the single endpoint: a VIES outage surfaces as VIES_UNAVAILABLE for that item instead of silently falling back.
• Partial-fill on quota. If your monthly quota runs out partway through a batch, items already processed keep their results and every remaining item gets a per-item RATE_LIMITED — the request itself still returns 200.

Error Codes

Per-item error codes use the same vocabulary as the single endpoint — full definitions in Error Handling.

Code Examples

JavaScript

async function validateVatBulk(vatIds) {
  const response = await fetch('https://api.vatnode.dev/v1/vat/bulk', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.VATNODE_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ vatIds })
  })

  if (!response.ok) {
    const error = await response.json()
    throw new Error(error.error.message)
  }

  return response.json()
}

// Usage
const { results, summary } = await validateVatBulk([
  'IE6388047V',
  'DE143454214',
  'DE12345'
])

console.log(`${summary.valid} valid, ${summary.invalid} invalid, ${summary.errors} errored`)

for (const result of results) {
  if (result.error) {
    console.warn(result.vatId, result.error.code, result.error.message)
  } else {
    console.log(result.vatId, result.valid ? 'valid' : 'invalid', result.source)
  }
}

Python

import requests
import os

def validate_vat_bulk(vat_ids):
    response = requests.post(
        'https://api.vatnode.dev/v1/vat/bulk',
        headers={'Authorization': f'Bearer {os.environ["VATNODE_API_KEY"]}'},
        json={'vatIds': vat_ids}
    )
    response.raise_for_status()
    return response.json()

# Usage
data = validate_vat_bulk(['IE6388047V', 'DE143454214', 'DE12345'])
print(f"{data['summary']['valid']} valid, {data['summary']['errors']} errored")

for result in data['results']:
    if result.get('error'):
        print(result['vatId'], result['error']['code'])
    else:
        print(result['vatId'], 'valid' if result['valid'] else 'invalid', result['source'])

How to Bulk-Validate a List of VAT Numbers

1. Collect the VAT IDs. Gather the VAT numbers you want to check — up to 100 per request — with their two-letter country prefix, e.g. from an imported customer or supplier list.
2. POST them to /v1/vat/bulk. Send the array as { "vatIds": [...] } in the request body with your live API key in the Authorization header. Set your EU VAT once in dashboard Settings to receive a consultation number per item automatically.
3. Read the per-item results and the summary. The response is always 200 OK. Each entry in results carries its own valid/source/error; summary.requested, valid, invalid and errors give you the batch total at a glance.
4. Handle partial failures. An item with an error field was not billed. Fix the input (INVALID_FORMAT) or retry later (VIES_UNAVAILABLE, RATE_LIMITED) — no need to resend the whole batch.

FAQ

See Also

• VAT Validation — the single-check endpoint, with full company enrichment and consultation-number details
• VIES API — what the underlying EU VIES register is and how vatnode wraps it
• Documentation — full API reference
• Pricing — monthly quotas and overage rates by plan