> ## 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 a VAT number > Validate a VAT number against the appropriate upstream service (VIES, HMRC, BFS, BRREG, or ABR) and return the validity status, company details, and an optional consultation number. Input is normalized automatically - spaces, dots, and casing are handled for you (`"nl 123.456.789 b01"` -> `"NL123456789B01"`). Results are cached for 25 days. Cached responses include `meta.cached: true` and `meta.cached_at`. Pass `cache=false` to bypass the cache and force a fresh lookup from the upstream service. ## OpenAPI ````yaml /openapi/public.yaml get /v1/validate 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: get: tags: - VAT Validation summary: Validate a VAT number description: >- Validate a VAT number against the appropriate upstream service (VIES, HMRC, BFS, BRREG, or ABR) and return the validity status, company details, and an optional consultation number. Input is normalized automatically - spaces, dots, and casing are handled for you (`"nl 123.456.789 b01"` -> `"NL123456789B01"`). Results are cached for 25 days. Cached responses include `meta.cached: true` and `meta.cached_at`. Pass `cache=false` to bypass the cache and force a fresh lookup from the upstream service. operationId: validateVatNumber parameters: - schema: type: string minLength: 1 description: >- The VAT number to validate (e.g. NL123456789B01, GB123456789, CHE-123.456.789 MWST, NO123456789MVA, AU51824753556). Supports EU, UK, CH, LI, NO, and AU formats. Will be normalized to uppercase with spaces and dots removed. example: NL123456789B01 required: true description: >- The VAT number to validate (e.g. NL123456789B01, GB123456789, CHE-123.456.789 MWST, NO123456789MVA, AU51824753556). Supports EU, UK, CH, LI, NO, and AU formats. Will be normalized to uppercase with spaces and dots removed. name: vat_number in: query - schema: type: string description: >- Your own VAT number, to receive a consultation number. For EU targets, provide an EU requester. For UK targets, provide a UK requester. example: DE987654321 required: false description: >- Your own VAT number, to receive a consultation number. For EU targets, provide an EU requester. For UK targets, provide a UK requester. name: requester_vat_number in: query - schema: type: string enum: - 'true' - 'false' default: 'true' description: >- Set to false to bypass the cache and force a fresh lookup from the upstream service. The fresh result is still cached for subsequent requests. Defaults to true. example: 'true' required: false description: >- Set to false to bypass the cache and force a fresh lookup from the upstream service. The fresh result is still cached for subsequent requests. Defaults to true. name: cache in: query responses: '200': description: VAT number validated successfully content: application/json: schema: $ref: '#/components/schemas/VatValidationSuccessResponse' '400': description: Missing required query parameter `vat_number` content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: missing_parameter message: 'Missing required query parameter: vat_number' docs_url: https://docs.avatcado.com/errors/missing_parameter 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 '422': description: Invalid VAT number format or unsupported country content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: invalid_vat_format message: >- The VAT number format is invalid. Expected format: CC123456789 docs_url: https://docs.avatcado.com/errors/invalid_vat_format meta: request_id: 550e8400-e29b-41d4-a716-446655440000 '429': description: Monthly quota or burst rate limit exceeded 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 '503': description: >- Upstream validation service (VIES, HMRC, BFS, BRREG, or ABR) error or unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: upstream_unavailable message: The upstream VAT validation service is currently unavailable docs_url: https://docs.avatcado.com/errors/upstream_unavailable meta: request_id: 550e8400-e29b-41d4-a716-446655440000 security: - bearerAuth: [] components: schemas: VatValidationSuccessResponse: type: object properties: data: $ref: '#/components/schemas/VatValidationData' 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 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 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 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) ````