Batch Validation

Validate up to 50 VAT numbers in one request. Available on Pro and Business tiers only. Each VAT number is validated independently against the appropriate upstream service (VIES, HMRC, BFS, Bronnoysund, or ABR). Results are returned in the same order as the input array.

POST /v1/validate/batch

Request body

Field	Type	Required	Description
`vat_numbers`	`string[]`	Yes	Array of VAT numbers to validate (1-50 items)
`requester_vat_number`	`string`	No	Your own VAT number, to receive consultation numbers
`cache`	`boolean`	No	Set to `false` to bypass the cache. Defaults to `true`, or to `false` when `requester_vat_number` is supplied (no stored result is served then, not even during an outage). Pass `true` explicitly to opt back in
`fallback`	`boolean`	No	Set to `false` so no item consults a national register when VIES is down (Pro and Business; ignored on Free). Defaults to `true`, or to `false` when `requester_vat_number` is supplied, because register answers never carry consultation numbers. Pass `true` explicitly to opt back in

Response shape

The response always returns HTTP 200 with a data object containing results and summary. Per-item errors appear inline in the results array rather than causing the entire request to fail.

Success result

{
  "data": {
    "valid": true,
    "vat_number": "NL123456789B01",
    "country_code": "NL",
    "company": {
      "name": "Acme B.V.",
      "address": "Keizersgracht 123, Amsterdam"
    },
    "requested_at": "2026-03-18T12:00:00Z"
  },
  "meta": {
    "source": "vies",
    "source_status": "cached",
    "cached": true,
    "stale": false,
    "cached_at": "2026-03-18T10:00:00Z"
  }
}

The data object is the same VatValidationData shape as the single validate endpoint. Per-item meta always contains source, source_status, cached and stale (plus cached_at when cached), the same as a single validate response. The optional fallback body field (default true) works like the query parameter on the single endpoint: fallback: false stops every item from consulting a national register during a VIES outage, for example when you need consultation numbers.

Error result

When an individual VAT number fails (e.g. upstream timeout, invalid format), its result contains an error object instead of data. The normalized vat_number that failed is echoed inside the error object (meta.vat_number is kept for backward compatibility but deprecated).

{
  "error": {
    "code": "upstream_unavailable",
    "message": "HMRC service unavailable",
    "vat_number": "XX000000000"
  },
  "meta": {
    "vat_number": "XX000000000"
  }
}

Summary

Every batch response includes a summary object:

{
  "total": 3,
  "succeeded": 2,
  "failed": 1
}

Full example response

{
  "data": {
    "results": [
      {
        "data": {
          "valid": true,
          "vat_number": "NL123456789B01",
          "country_code": "NL",
          "company": {
            "name": "Acme B.V.",
            "address": "Keizersgracht 123, Amsterdam"
          },
          "requested_at": "2026-03-18T12:00:00Z"
        },
        "meta": {
          "source": "vies",
          "source_status": "cached",
          "cached": true,
          "stale": false,
          "cached_at": "2026-03-18T10:00:00Z"
        }
      },
      {
        "data": {
          "valid": true,
          "vat_number": "DE987654321",
          "country_code": "DE",
          "company": {
            "name": "Beispiel GmbH",
            "address": "Berliner Str. 42, Berlin"
          },
          "requested_at": "2026-03-18T12:00:01Z"
        },
        "meta": {
          "source": "vies",
          "source_status": "live",
          "cached": false,
          "stale": false
        }
      },
      {
        "error": {
          "code": "upstream_unavailable",
          "message": "VIES service unavailable",
          "vat_number": "FR12345678901"
        },
        "meta": {
          "vat_number": "FR12345678901"
        }
      }
    ],
    "summary": {
      "total": 3,
      "succeeded": 2,
      "failed": 1
    }
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "request_duration_ms": 850
  }
}

Deduplication

Duplicate VAT numbers in the input array are deduplicated internally. Only unique numbers are validated against the upstream service and counted toward your monthly quota. The response still returns one result per input item in the original order — duplicates receive the same result. For example, sending ["NL123456789B01", "NL123456789B01", "DE987654321"] validates 2 unique numbers and returns 3 results.

Examples

curl -X POST https://api.avatcado.com/v1/validate/batch \
  -H "Authorization: Bearer avat_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "vat_numbers": ["NL123456789B01", "DE987654321", "GB123456789"],
    "requester_vat_number": "FR99999999999"
  }'

import Avatcado, { isBatchSuccess } from "@avatcado/node";

const avatcado = new Avatcado("avat_live_your_api_key");
const { data, error } = await avatcado.vat.validateBatch({
  vatNumbers: ["NL123456789B01", "DE987654321", "GB123456789"],
  requesterVatNumber: "FR99999999999",
});

if (error) {
  // HTTP-level error (401, 403, 422, 429)
  console.error(`${error.code}: ${error.message}`);
} else {
  // Check each result for inline errors
  for (const item of data.data.results) {
    if (isBatchSuccess(item)) {
      console.log(`${item.data.vatNumber}: valid=${item.data.valid}`);
    } else {
      console.error(`${item.meta.vatNumber}: ${item.error.code}`);
    }
  }
  console.log(`Summary: ${data.data.summary.succeeded}/${data.data.summary.total} succeeded`);
}

from avatcado import Avatcado, is_batch_success

avatcado = Avatcado("avat_live_your_api_key")
result = avatcado.vat.validate_batch(["NL123456789B01", "DE987654321", "GB123456789"])

# Check each result for inline errors
for item in result.results:
    if is_batch_success(item):
        print(f"{item.data.vat_number}: valid={item.data.valid}")
    else:
        print(f"{item.error.vat_number}: {item.error.code}")
print(f"Summary: {result.summary.succeeded}/{result.summary.total} succeeded")

Error handling

Batch validation has two levels of errors:

HTTP-level errors

These prevent the entire batch from executing. The response shape is the standard { error, meta } envelope.

HTTP Status	Error Code	Cause
401	`unauthorized`	Invalid or missing API key
403	`tier_insufficient`	Free tier — upgrade to Pro or Business
422	`validation_error`	Invalid request body (e.g. empty array, >50 items)
429	`rate_limit_exceeded`	Monthly quota insufficient for this batch

Inline errors

When the batch executes but individual VAT numbers fail, those failures appear as inline errors in the results array. The HTTP status is still 200 and the summary.failed count tells you how many items had errors. Common inline error codes: invalid_vat_format, upstream_unavailable.

Always check both levels: first error for HTTP-level failures, then iterate data.data.results for inline per-item errors. With the Node.js SDK, use isBatchSuccess() to type-narrow each result. With the Python SDK, use is_batch_success().

Getting Started

Core Concepts

Guides

Errors

Batch Validation

Batch Validation

Request body

Response shape

Success result

Error result

Summary

Full example response

Deduplication

Examples

Error handling

HTTP-level errors

Inline errors

​Batch Validation

​Request body

​Response shape

​Success result

​Error result

​Summary

​Full example response

​Deduplication

​Examples

​Error handling

​HTTP-level errors

​Inline errors

Batch Validation

Request body

Response shape

Success result

Error result

Summary

Full example response

Deduplication

Examples

Error handling

HTTP-level errors

Inline errors