Quickstart

Get your API key

Sign up at avatcado.com to get your API key. Keys use the format avat_live_xxx.Want to test your integration first? Use a avat_test_ key for test mode - no upstream calls, no quota usage, predictable results.Store your key securely - it will only be shown once. Avatcado stores a SHA-256 hash, never the raw key.

Make your first request

Install the SDK for your language:

npm install @avatcado/node   # Node.js
pip install avatcado          # Python

curl -H "Authorization: Bearer avat_live_your_api_key" \
  "https://api.avatcado.com/v1/validate?vat_number=NL123456789B01"

import Avatcado from "@avatcado/node";

const avatcado = new Avatcado("avat_live_your_api_key");
const { data, error } = await avatcado.vat.validate({ vatNumber: "NL123456789B01" });

from avatcado import Avatcado

avatcado = Avatcado("avat_live_your_api_key")
result = avatcado.vat.validate("NL123456789B01")

Handle the response

Every response has the same shape: data or error, plus meta.

{
  "data": {
    "valid": true,
    "vat_number": "NL123456789B01",
    "country_code": "NL",
    "company": {
      "name": "Acme B.V.",
      "address": "Keizersgracht 123, Amsterdam"
    },
    "requested_at": "2026-03-06T12:00:00Z"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "request_duration_ms": 120,
    "source": "vies",
    "source_status": "live",
    "cached": false,
    "stale": false
  }
}

data.valid: true if the VAT number is active and registered
data.company: Company name and address; null when the number is invalid or the registry publishes no company data (Germany and Spain via VIES)
meta.request_id: Unique ID for debugging, also in the X-Request-Id header
meta.request_duration_ms: How long the request took in milliseconds
meta.source: Which registry produced the result ("vies", "hmrc", a national registry id, and so on)
meta.source_status: How the result was obtained ("live", "cached", "unavailable", "degraded", or "fallback", the last one on Pro and Business plans when a national register answered for a VIES member state that was down)
meta.cached: Whether this result came from cache
meta.stale: Whether the served row is older than the 25-day TTL

Handle errors

Every error response has the same shape. Check response.error to handle failures:

curl -s -H "Authorization: Bearer avat_live_your_api_key" \
  "https://api.avatcado.com/v1/validate?vat_number=INVALID" | jq .
# Check for .error in the JSON response

import Avatcado from "@avatcado/node";

const avatcado = new Avatcado("avat_live_your_api_key");
const { data, error } = await avatcado.vat.validate({ vatNumber: "NL123456789B01" });

if (error) {
  console.error(`${error.code}: ${error.message}`);
  // See docsUrl for details on this specific error
  console.error(error.docsUrl);
} else {
  console.log(`Valid: ${data.data.valid}`);
}

from avatcado import Avatcado, AvatcadoError

avatcado = Avatcado("avat_live_your_api_key")

try:
    result = avatcado.vat.validate("NL123456789B01")
    print(f"Valid: {result.data.valid}")
except AvatcadoError as e:
    print(f"{e.code}: {e.message}")
    # See docs_url for details on this specific error
    print(e.docs_url)

Input normalization: You can pass messy input like "nl 123.456.789 b01" and the API will normalize it to NL123456789B01 automatically. No need to clean up VAT numbers before sending them.

Getting Started

Core Concepts

Guides

Errors

Quickstart

Quickstart

​Quickstart

Quickstart