Validate VAT Number

GET /v1/validate Validate a VAT number against VIES (EU) or HMRC (UK) and return the validity status, company details, and an optional consultation number.

Authentication

Query parameters

Parameter	Type	Required	Description
`vat_number`	`string`	Yes	The VAT number to validate (e.g., `NL123456789B01`, `GB123456789`)
`requester_vat_number`	`string`	No	Your own VAT number, to receive a consultation number from VIES

Examples

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

With requester VAT number

To receive a consultation number (Business and Scale tiers), include your own VAT number:

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

Response examples

Valid VAT number

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

Invalid VAT number

{
  "data": {
    "valid": false,
    "vat_number": "NL000000000B00",
    "country_code": "NL",
    "company": null,
    "consultation_number": null,
    "requested_at": "2026-03-06T12:00:00Z"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440001",
    "cached": false
  }
}

Cached result

{
  "data": {
    "valid": true,
    "vat_number": "NL123456789B01",
    "country_code": "NL",
    "company": {
      "name": "Acme B.V.",
      "address": "Keizersgracht 123, Amsterdam"
    },
    "requested_at": "2026-03-06T10:00:00Z"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440002",
    "cached": true,
    "cached_at": "2026-03-06T10:00:00Z"
  }
}

Test mode response

When using a vtly_test_ key, responses include meta.mode: "test" and use magic VAT numbers for predictable results:

{
  "data": {
    "valid": true,
    "vat_number": "DE111111111",
    "country_code": "DE",
    "company": {
      "name": "Test GmbH",
      "address": "Musterstrasse 1, Berlin"
    },
    "requested_at": "2026-03-07T12:00:00Z"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440003",
    "cached": false,
    "mode": "test"
  }
}

Response headers

Header	Description
`X-Request-Id`	Unique request identifier (echoes client-provided value if sent)
`X-RateLimit-Limit`	Total requests allowed this period
`X-RateLimit-Remaining`	Requests remaining this period
`X-RateLimit-Reset`	When the quota resets (ISO 8601)

Possible errors

Error Code	Status	When
`missing_parameter`	400	`vat_number` query parameter is missing
`invalid_vat_format`	422	VAT number format unrecognized or unsupported country
`unauthorized`	401	Invalid or missing API key
`rate_limit_exceeded`	429	Monthly quota exhausted
`upstream_error`	503	HMRC returned an error
`upstream_unavailable`	503	VIES or HMRC unreachable

Endpoints

​Validate VAT Number

​Authentication

​Query parameters

​Examples

​With requester VAT number

​Response examples

​Valid VAT number

​Invalid VAT number

​Cached result

​Test mode response

​Response headers

​Possible errors