> ## Documentation Index > Fetch the complete documentation index at: https://docs.avatcado.com/llms.txt > Use this file to discover all available pages before exploring further. # Validate multiple VAT numbers > Validate up to 50 VAT numbers in a single request. Each VAT number is validated independently against the appropriate upstream service (VIES, HMRC, BFS, BRREG, or ABR). Results are returned in the same order as the input array. Duplicate VAT numbers are deduplicated internally. Only unique numbers count against your monthly quota. Per-item errors are returned inline in the results array; the overall response is always 200. Available to Pro and Business tiers only. ## OpenAPI ````yaml /openapi/public.yaml post /v1/validate/batch openapi: 3.1.0 info: title: Avatcado API version: '1.0' description: >- Validate VAT and GST numbers across 32 countries with a single API call. Get company details, consultation numbers, and validity status from VIES, HMRC, BFS, BRREG, and ABR, with caching, rate limiting, and structured error responses built in. contact: name: Avatcado url: https://docs.avatcado.com servers: - url: https://api.avatcado.com description: Production security: [] paths: /v1/validate/batch: post: tags: - VAT Validation summary: Validate multiple VAT numbers description: >- Validate up to 50 VAT numbers in a single request. Each VAT number is validated independently against the appropriate upstream service (VIES, HMRC, BFS, BRREG, or ABR). Results are returned in the same order as the input array. Duplicate VAT numbers are deduplicated internally. Only unique numbers count against your monthly quota. Per-item errors are returned inline in the results array; the overall response is always 200. Available to Pro and Business tiers only. operationId: batchValidateVatNumbers requestBody: content: application/json: schema: $ref: '#/components/schemas/BatchValidateBody' responses: '200': description: Batch validation completed. Per-item errors are inline in results. content: application/json: schema: $ref: '#/components/schemas/BatchValidationResponse' '401': description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unauthorized message: Missing or invalid API key docs_url: https://docs.avatcado.com/errors/unauthorized meta: request_id: 550e8400-e29b-41d4-a716-446655440000 '403': description: Batch validation requires Pro or Business tier content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: tier_insufficient message: Batch validation requires a Pro or Business plan docs_url: https://docs.avatcado.com/errors/tier_insufficient meta: request_id: 550e8400-e29b-41d4-a716-446655440000 '422': description: Invalid request body content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: validation_error message: At least one VAT number is required docs_url: https://docs.avatcado.com/errors/validation_error meta: request_id: 550e8400-e29b-41d4-a716-446655440000 '429': description: Monthly quota insufficient for this batch content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: rate_limit_exceeded message: Monthly validation limit exceeded docs_url: https://docs.avatcado.com/errors/rate_limit_exceeded meta: request_id: 550e8400-e29b-41d4-a716-446655440000 security: - bearerAuth: [] components: schemas: BatchValidateBody: type: object properties: vat_numbers: type: array items: type: string minLength: 1 minItems: 1 maxItems: 50 description: Array of VAT numbers to validate (max 50) example: - NL123456789B01 - DE987654321 - GB123456789 - CHE123456789MWST - NO123456789MVA - AU51824753556 requester_vat_number: type: string description: >- Your own VAT number, to receive consultation numbers. For EU targets, provide an EU requester. For UK targets, provide a UK requester. example: DE987654321 cache: type: boolean default: true description: >- Set to false to bypass the cache and force fresh lookups. Defaults to true. example: true required: - vat_numbers BatchValidationResponse: type: object properties: data: type: object properties: results: type: array items: anyOf: - $ref: '#/components/schemas/BatchResultSuccess' - $ref: '#/components/schemas/BatchResultError' summary: $ref: '#/components/schemas/BatchSummary' required: - results - summary meta: $ref: '#/components/schemas/BatchResponseMeta' required: - data - meta ErrorResponse: type: object properties: error: $ref: '#/components/schemas/ErrorDetail' meta: $ref: '#/components/schemas/ResponseMeta' required: - error - meta BatchResultSuccess: type: object properties: data: $ref: '#/components/schemas/VatValidationData' meta: $ref: '#/components/schemas/BatchItemCacheMeta' required: - data - meta BatchResultError: type: object properties: error: type: object properties: code: type: string example: upstream_unavailable message: type: string example: HMRC service unavailable required: - code - message meta: $ref: '#/components/schemas/BatchItemErrorMeta' required: - error - meta BatchSummary: type: object properties: total: type: integer example: 3 description: Total number of VAT numbers in the request succeeded: type: integer example: 2 description: Number of successfully validated VAT numbers failed: type: integer example: 1 description: Number of VAT numbers that failed validation required: - total - succeeded - failed BatchResponseMeta: type: object properties: request_id: type: string example: 550e8400-e29b-41d4-a716-446655440000 description: Unique identifier for this request mode: type: string enum: - test description: Present with value 'test' when using an avat_test_ API key request_duration_ms: type: integer description: Total request processing time in milliseconds example: 120 required: - request_id ErrorDetail: type: object properties: code: type: string description: Machine-readable error code example: missing_parameter message: type: string description: Human-readable error message example: Query parameter 'vat_number' is required docs_url: type: string description: Link to documentation for this error code example: https://docs.avatcado.com/errors/missing_parameter required: - code - message ResponseMeta: type: object properties: request_id: type: string example: 550e8400-e29b-41d4-a716-446655440000 description: Unique identifier for this request cached: type: boolean description: Whether this result was served from cache cached_at: type: string description: >- When the result was originally cached (only present when cached is true) stale: type: boolean description: >- Whether this is a stale cache result served because the upstream was unavailable source_status: type: string enum: - live - unavailable - degraded description: >- Upstream data source reliability. 'live' = confirmed fresh result. 'unavailable' = upstream source was down, stale cache served. 'degraded' = result may be unreliable (possible silent false negative from VIES, BFS, or BRREG). example: live mode: type: string enum: - test description: Present with value 'test' when using an avat_test_ API key request_duration_ms: type: integer description: Total request processing time in milliseconds example: 120 required: - request_id VatValidationData: type: object properties: valid: type: boolean description: Whether the VAT number is valid according to the upstream authority example: true vat_number: type: string description: The normalized VAT number that was validated example: NL123456789B01 country_code: type: string description: Two-letter country code extracted from the VAT number example: NL company: $ref: '#/components/schemas/CompanyInfo' consultation_number: type: string description: >- Consultation number from VIES (EU) or HMRC (UK). Only present when requester_vat_number is provided. Not available for CH, LI, NO, or AU validations. example: WAPIAAAAA1BBB2 requested_at: type: string description: When the validation was performed (or originally cached) example: '2026-03-06T12:00:00.000Z' required: - valid - vat_number - country_code - company - requested_at BatchItemCacheMeta: type: object properties: cached: type: boolean description: Whether this result was served from cache cached_at: type: string description: When the result was originally cached stale: type: boolean description: >- Whether this is a stale cache result served because the upstream was unavailable source_status: type: string enum: - live - unavailable - degraded description: >- Upstream data source reliability. 'live' = confirmed fresh result. 'unavailable' = upstream source was down, stale cache served. 'degraded' = result may be unreliable (possible silent false negative from VIES, BFS, or BRREG). example: live BatchItemErrorMeta: type: object properties: vat_number: type: string example: XX000000000 description: The VAT number that failed validation required: - vat_number CompanyInfo: type: object nullable: true properties: name: type: string example: Acme B.V. description: Registered company name address: type: string nullable: true example: Keizersgracht 123, Amsterdam description: Registered company address required: - name - address description: Company details returned by the upstream authority (null if invalid) ````