LookupTax SDK for Python

Validate tax IDs — VAT, EIN, GSTIN, ABN and more — against official government registries.

lookuptax.com

pip install lookuptax

Python 3.9+.

Quick start

from lookuptax import LookupTax

with LookupTax(api_key="...") as lookuptax:
    res = lookuptax.validate("IE", "53057102A")

    if res.result.status == "VALID":
        print("Confirmed:", res.entity.name)

Read result.status, not isValid

Every response carries a result whose status is the single source of truth. Five mutually exclusive values:

Do not branch on validation["overall"]["isValid"]: it is true for VALID, UNVERIFIED and INDETERMINATE alike, so a format-only pass looks identical to a registry-confirmed one.

Two helpers encode that correctly:

res.result.is_valid      # True only for VALID — UNVERIFIED is not "valid"
res.result.should_retry  # True only for INDETERMINATE

match res.result.status:
    case "VALID":         accept(res.entity)
    case "INVALID":       reject(res.result.reason)
    case "UNVERIFIED":    accept_with_caveat()   # format checked only
    case "INDETERMINATE": retry_later()          # registry was down
    case "UNSUPPORTED":   skip()

Errors vs outcomes

The SDK mirrors the API's split:

• Validation outcomes return. An INVALID tax ID is a successful call — you get a response, not an exception. UNSUPPORTED returns too, even though it arrives as HTTP 422, because the body still carries a result.
• Request errors raise. Authentication, quota, rate limit, malformed request — the call could not be processed at all.

from lookuptax import LookupTaxError, QuotaExceededError, RateLimitError

try:
    res = lookuptax.validate("IE", "53057102A")
except RateLimitError as e:
    time.sleep(e.retry_after or 1)
except QuotaExceededError:
    notify_billing()
except LookupTaxError as e:
    log.error("%s (%s)", e.code, e.status)

Branch on e.code (a stable machine-readable string), never on the message.

Transient failures — 429, 500, 503 — retry automatically (2 attempts by default, honouring Retry-After). Pass max_retries=0 to opt out. Batch submission is never retried automatically, because a retried submission that actually succeeded would create a second batch and reserve quota twice.

EU routing

lookuptax.validate("DE", "DE123456789", validation_source="vies")   # VIES only
lookuptax.validate("DE", "DE123456789", validation_source="local")  # national registry only

With vies or local there is no fallback to the other — if the requested source cannot answer you get INDETERMINATE rather than a silent answer from the other one, which is what makes it usable for reconciliation. Default is auto. Ignored outside VIES-covered countries.

Countries needing a name

lookuptax.validate("MX", "XAXX010101000", additional_params={"name": "Empresa Ejemplo SA de CV"})

Batch

Up to 100 IDs, validated asynchronously. Enterprise plan only.

from lookuptax import TaxIdInput

batch = lookuptax.create_batch([
    TaxIdInput("IE", "53057102A"),
    TaxIdInput("MX", "XAXX010101000", name="Empresa Ejemplo SA de CV"),
])

done = lookuptax.wait_for_batch(batch["batch_id"])

for item in lookuptax.iterate_batch_results(batch["batch_id"]):
    print(item.tin, item.validation_result.result.status if item.validation_result else item.status)

wait_for_batch polls on a relaxed cadence by design. When a registry is unreachable an item keeps retrying for roughly three days, carrying a next_retry_at — a long-running item is not a stuck one.

Configuration

LookupTax(
    api_key="...",                              # required
    base_url="https://api.lookuptax.com/v1",    # default
    timeout=30.0,                               # seconds, per request
    max_retries=2,                              # 429/500/503 only
    client=httpx.Client(...),                   # inject a proxy/transport, or for tests
)

base_url is configurable because the published path prefix is deployment configuration rather than a property of the SDK.

API

License

MIT