Docs menu: Lookups

Lookups

Check a VAT number against a public registry.

On this page

Look up a VAT number

Look up a VAT number #

GET /api/v1/tax_ids/lookup

Checks a VAT number with the EU's VIES service (a test key gets the sandbox) and returns whether it is an active registration, with the registered name and address when the member state shares them. A Greek ΑΦΜ with a wrong check digit is refused before any registry is asked. When VIES or the member state's registry is unavailable the answer is 503 service_unavailable, retryable. Answers are reused for up to a day.

Bearer API key

Query parameters

countrystringrequired: ISO 3166-1 alpha-2 country of the VAT registration: GR for Greece (not the VAT prefix EL).
One of: AT, BE, BG, CY, CZ, DE, DK, EE, ES, FI, FR, GR, HR, HU, IE, IT, LT, LU, LV, MT, NL, PL, PT, RO, SE, SI, SK, XI
codestringrequired: The VAT number without its country prefix; spaces, hyphens and dots are removed and letters upper-cased. A Greek ΑΦΜ (9 digits) is checked for its check digit first.
Up to 60 characters

Request

curl

curl -X GET 'https://tallio.dev/api/v1/tax_ids/lookup?country=GR&code=666666662' \
  -H "Authorization: Bearer $TALLIO_API_KEY"

TypeScript SDK

import { createTallioClient, unwrap } from "@tallio/sdk";

const tallio = createTallioClient({
  apiKey: process.env.TALLIO_API_KEY!,
  baseUrl: "https://tallio.dev",
});

const result = await unwrap(tallio.http.GET("/api/v1/tax_ids/lookup", {
  params: {
    query: {
      country: "GR",
      code: "666666662",
    },
  },
}));

Responses
Status	Description
`200`	What the registry says.
4XX, 5XX	An error: see Errors below.

Response body · 200

dataobjectrequired

A VAT number checked against a registry. Tallio reports only what the registry returns and never fills in a name or address of its own.

Show nested fields (8)

objectstringrequired: Always "tax_id_lookup".
Always tax_id_lookup
countrystringrequired: The country looked up.
One of: AT, BE, BG, CY, CZ, DE, DK, EE, ES, FI, FR, GR, HR, HU, IE, IT, LT, LU, LV, MT, NL, PL, PT, RO, SE, SI, SK, XI
codestringrequired: The VAT number looked up, normalised.
validbooleanrequired: Whether the registry reports the number as an active VAT registration.
namestring | nullrequired: The registered name as the registry gives it; null when it shares none or the number is not valid.
addressstring | nullrequired: The registered address as one line, as the registry gives it; null when it shares none.
sourcestringrequired: Who answered: vies (the EU VAT Information Exchange System) or sandbox (test keys).
One of: vies, sandbox
checked_atstringrequired: When the registry answered; a repeat lookup within a day may reuse that answer.
Format: date-time

Example response · 200

{
  "data": {
    "object": "tax_id_lookup",
    "country": "GR",
    "code": "666666662",
    "valid": true,
    "name": "Kafeneio Lemonia IKE",
    "address": null,
    "source": "sandbox",
    "checked_at": "2026-10-13T17:20:42.364Z"
  }
}

Response headers

x-request-idstring: The request's correlation id; quote it when reporting a problem. One of: req_ plus a uuid (Tallio made it), client: plus the x-request-id you sent (8-128 of A-Z a-z 0-9 . _ : -), or the hosting platform's id.
With every response
Show patternHide pattern
^(?:req_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|client:[A-Za-z0-9._:-]{8,128}|[A-Za-z0-9._-]{1,16}::[A-Za-z0-9._:-]{6,110})$
ratelimit-limitinteger: Requests allowed in the current window for the bucket this request counted against.
With 200, 400, 429, 503 · At least 1
ratelimit-remaininginteger: Requests left in the current window; 0 means the next one is refused until the window resets.
With 200, 400, 429, 503 · At least 0
ratelimit-resetinteger: Seconds until the current window resets.
With 200, 400, 429, 503 · At least 0
www-authenticatestring: The bearer challenge: send a vendor secret key as Authorization: Bearer <key>.
With 401 · Always Bearer realm="tallio"
retry-afterinteger: Seconds to wait before retrying a request refused with 429 rate_limited.
With 429 · At least 1

Errors
Code	Status	Retryable	Meaning
`validation_failed`	400	No	Request validation failed.
`unauthorized`	401	No	Authentication is required.
`rate_limited`	429	Yes	A rate limit was reached. Retry later.
`internal_error`	500	No	An unexpected server error occurred.
`service_unavailable`	503	Yes	A service Tallio depends on is temporarily unavailable.