API reference · v1

Vatlas API documentation

One REST API, three entry points, one JSON envelope. Everything is a GET, everything is UTF-8, and every date is UTC in ISO 8601.

Base URL

https://api.vatlas.dev

Paths are versioned (/v1/…). A version never changes shape in a breaking way: a new field may appear, none is ever removed.

Authentication

Every call carries a key as a bearer token in the Authorization header. You can create as many keys as you like — they all draw on the same account quota, so a key is there to tell you which of your integrations made a call.

curl "https://api.vatlas.dev/v1/vat/FR08000325175" \
  -H "Authorization: Bearer vtl_live_xxxxxxxxxxxxxxxxxxxx"

A missing, unknown or revoked key answers 401 with the standard error envelope, and is not counted. Create your key — the Free plan is free and needs no card.

Response envelope

Success always carries data and meta. An error always carries error, and meta whenever sources were consulted. The shape does not change with the origin of the data: your code has nothing to branch on.

• meta.origin — database, source or vies.
• meta.source — SIRENE, MF_WL, PRH, RIK, UR_VID or VIES.
• meta.sourceUpdatedAt — UTC timestamp of the data served.
• meta.checked — every source consulted, in order.

Resolve a VAT number

GET /v1/vat/{vatNumber}

The heart of the API. Input is normalised before validation: case, spaces, dots and dashes are ignored, and Greece's ISO prefix GR is accepted alongside its VAT prefix EL. data.vatNumber always comes back in canonical form.

Request

curl "https://api.vatlas.dev/v1/vat/FR08000325175" \
  -H "Authorization: Bearer $VATLAS_KEY"

Response — 200 OK

{
  "data": {
    "vatNumber": "FR08000325175",
    "countryCode": "FR",
    "nationalNumber": "08000325175",
    "nationalId": "000325175",
    "name": "THIERRY JANOYER",
    "legalForm": "1000",
    "status": "active",
    "address": {
      "line1": "51 RUE MARX DORMOY",
      "line2": null,
      "postalCode": "13004",
      "city": "MARSEILLE",
      "country": "FR"
    }
  },
  "meta": {
    "origin": "database",
    "source": "SIRENE",
    "sourceUpdatedAt": "2025-12-06T09:43:55.000Z",
    "checked": ["database"]
  }
}

Response fields

List every country and how it is served

GET /v1/countries

Returns all 28 prefixes — the 27 member states plus Northern Ireland — with the source behind each and its strategy: bulk for an imported register, on-demand for the register's own API, both, or vies for a member state with no usable local source, which still resolves through the VIES fallback.

{
  "data": [
    { "countryCode": "FR", "name": "France",   "source": "SIRENE",  "strategy": "bulk" },
    { "countryCode": "PL", "name": "Poland",   "source": "MF_WL",   "strategy": "on-demand" },
    { "countryCode": "CZ", "name": "Czechia",  "source": "ARES",    "strategy": "on-demand" },
    { "countryCode": "FI", "name": "Finland",  "source": "PRH",     "strategy": "both" },
    { "countryCode": "DE", "name": "Germany",  "source": "VIES",    "strategy": "vies" }
  ]
}

Liveness probe

GET /health

Answers only once a database round trip has succeeded, so it works as-is for a readiness probe. This call costs no quota.

{ "status": "ok" }

Error codes

Every error shares the same shape:

{
  "error": {
    "code": "INVALID_VAT_FORMAT",
    "message": "Unknown VAT country prefix \"XX\"",
    "reason": "UNKNOWN_COUNTRY"
  }
}

Quotas & limits

The quota is monthly and belongs to the account, not to an individual key. Every metered response carries the current state of the counter, so there is nothing to estimate:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1788220800

• A 400 format error is never counted: the number is rejected before any source is consulted.
• A 503 is not counted either — a member state failed to answer, and that is not your call to pay for.
• /v1/countries and /health need no key and cost no quota.
• Quota exhausted: 429, with the same error envelope. X-RateLimit-Reset says when it renews.

Plan details on the pricing page.

Code samples

curl -s "https://api.vatlas.dev/v1/vat/FR08000325175" \
  -H "Authorization: Bearer $VATLAS_KEY" \
  | jq '.data.name'

// Node 20+ / Deno / browser (through your backend)
const lookupVat = async (vatNumber) => {
  const res = await fetch(
    `https://api.vatlas.dev/v1/vat/${encodeURIComponent(vatNumber)}`,
    { headers: { 'Authorization': `Bearer ${process.env.VATLAS_KEY}` } },
  )

  const payload = await res.json()
  if (!res.ok) throw new Error(`${payload.error.code}: ${payload.error.message}`)

  return payload.data
}

const company = await lookupVat('FR08000325175')
console.log(company.name, '—', company.address.city)

import os
import requests

def lookup_vat(vat_number: str) -> dict:
    res = requests.get(
        f"https://api.vatlas.dev/v1/vat/{vat_number}",
        headers={"Authorization": f"Bearer {os.environ['VATLAS_KEY']}"},
        timeout=10,
    )
    payload = res.json()

    if res.status_code != 200:
        raise RuntimeError(payload["error"]["code"])

    return payload["data"]

company = lookup_vat("FR08000325175")
print(company["name"], company["address"]["city"])

<?php

function lookupVat(string $vatNumber): array
{
    $context = stream_context_create([
        'http' => ['header' => 'Authorization: Bearer ' . getenv('VATLAS_KEY')],
    ]);

    $url = 'https://api.vatlas.dev/v1/vat/' . rawurlencode($vatNumber);
    $payload = json_decode(file_get_contents($url, false, $context), true);

    if (isset($payload['error'])) {
        throw new RuntimeException($payload['error']['code']);
    }

    return $payload['data'];
}

$company = lookupVat('FR08000325175');
echo $company['name'];