> ## 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 asynchronously

> Submit an array of VAT numbers for asynchronous validation. Returns 202 immediately with an accepted/rejected breakdown. Items with invalid formats are rejected inline in the response (never queued). Results for all accepted items are delivered as a single `batch.completed` webhook event.

Pro tier: max 200 items. Business tier: max 1000 items. Test keys are rejected.



## OpenAPI

````yaml /openapi/public.yaml post /v1/validate/async/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/async/batch:
    post:
      tags:
        - Async Validation
      summary: Validate multiple VAT numbers asynchronously
      description: >-
        Submit an array of VAT numbers for asynchronous validation. Returns 202
        immediately with an accepted/rejected breakdown. Items with invalid
        formats are rejected inline in the response (never queued). Results for
        all accepted items are delivered as a single `batch.completed` webhook
        event.


        Pro tier: max 200 items. Business tier: max 1000 items. Test keys are
        rejected.
      operationId: asyncBatchValidateVatNumbers
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AsyncBatchRequest'
      responses:
        '202':
          description: Batch accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncBatchResponse'
        '400':
          description: No webhook URL configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: webhook_not_configured
                  message: >-
                    Configure a webhook URL before using async validation. See
                    https://docs.avatcado.com/webhooks
                  docs_url: https://docs.avatcado.com/errors/webhook_not_configured
                meta:
                  request_id: 550e8400-e29b-41d4-a716-446655440000
        '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: >-
            Async validation requires Pro or Business tier, or the key is a test
            key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: tier_insufficient
                  message: Async 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: Batch size exceeds tier limit or 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:
    AsyncBatchRequest:
      type: object
      properties:
        vat_numbers:
          type: array
          items:
            type: string
            minLength: 1
          minItems: 1
          description: >-
            Array of VAT numbers to validate (max 200 for Pro, 1000 for
            Business)
          example:
            - DE123456789
            - NL987654321B01
        requester_vat_number:
          type: string
          description: Your own VAT number (for consultation numbers)
          example: NL987654321B01
        cache:
          type: boolean
          default: true
          description: Whether to use cached results
          example: true
      required:
        - vat_numbers
    AsyncBatchResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            batch_id:
              type: string
              nullable: true
              description: >-
                Unique identifier for this batch (null when every item was
                rejected)
              example: 550e8400-e29b-41d4-a716-446655440000
            status:
              type: string
              enum:
                - pending
                - completed
              description: >-
                `pending` for queued batches, `completed` for all-rejected
                batches that were never queued
              example: pending
            total:
              type: integer
              description: Total number of items submitted
              example: 200
            accepted:
              type: integer
              description: Number of items accepted for processing
              example: 197
            rejected:
              type: array
              items:
                type: object
                properties:
                  vat_number:
                    type: string
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - vat_number
                  - error
              description: Items rejected due to invalid format
          required:
            - batch_id
            - status
            - total
            - accepted
            - rejected
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      required:
        - data
        - meta
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      required:
        - error
        - meta
    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
    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

````