Skip to main content

​
Quickstart

1

Get your API key

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

Make your first request

Install the SDK for your language:
npm install @vatly/node   # Node.js
pip install vatly          # Python

curl -H "Authorization: Bearer vtly_live_your_api_key" \
  "https://api.vatly.dev/v1/validate?vat_number=NL123456789B01"
3

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,
    "cached": false
  }
}
  • data.valid: true if the VAT number is active and registered
  • data.company: Company name and address (when available and valid)
  • 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.cached: Whether this result came from cache
4

Handle errors

Every error response has the same shape. Check response.error to handle failures:
curl -s -H "Authorization: Bearer vtly_live_your_api_key" \
  "https://api.vatly.dev/v1/validate?vat_number=INVALID" | jq .
# Check for .error in the JSON response
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.