Skip to main content

VerifNow Python SDK

PyPI Python CI License: Apache-2.0

Official Python SDK for the VerifNow validation API. One API key for email, phone, IBAN, VAT (VIES), SSN, SIN and NIF validation.

Fully typed, no runtime dependencies, sync and asyncio clients.

Install

pip install verifnow

Requires Python 3.10 or later.

Getting an API key

  1. Create an account at app.verifnow.io.
  2. Create an API key from the dashboard.
  3. Keep it server-side. It authorises calls against your quota — never ship it to a browser.

The Free plan gives you 250 validations a month with the full STANDARD check set, no credit card.

Quick start

from verifnow import VerifNow

client = VerifNow()  # reads the VERIFNOW_API_KEY environment variable

result = client.validate_email("user@exmaple.com")

result.valid             # False
result.message           # "Email address is unlikely to be deliverable"
result.normalized_value  # None when invalid

# Turn a typo into a correction prompt instead of a rejection
signals = result.email_details.signals if result.email_details else None
if signals and signals.typo_detected:
    print(f"Did you mean {signals.suggested_domain}?")  # "example.com"

Pass the key explicitly with VerifNow("vn_...") if you do not use the environment variable. Create one client and share it: it holds no per-request state and is safe across threads.

VAT and VIES

VAT is the one validator whose answer can be unknown rather than yes or no. Registration is checked against VIES, the European Commission's registry, which publishes no SLA and drops member states several times a month.

result = client.validate_vat("IE6388047V")
vat = result.vat_details

vat.format_valid  # True — structural, decided locally, never depends on VIES
vat.registered    # True | False | None
vat.source        # "LIVE" | "CACHE" | "STALE" | "UNVERIFIED" | "NOT_APPLICABLE"
vat.trader_name   # "GOOGLE IRELAND LIMITED" — when the member state discloses it

registered is None means unknown, never "not registered." It is what you get when VIES could not be consulted. Treating it as False rejects legitimate businesses during someone else's outage:

if not vat.format_valid:
    return reject("That VAT number is not correctly formed.")
if vat.registered is False:
    return reject("That VAT number is not registered.")

if vat.registered is None:
    # Accept, record that it is unconfirmed, and re-check later.
    queue_for_recheck(vat_number)
    return accept(verified=False)

return accept(verified=True, stale=vat.source == "STALE")

Use is False and is None, not not vat.registered: the latter lumps the two together.

Does the number belong to this company?

Pass the name you expect — from a supplier form, for instance — and the response says whether it matches the registered holder:

result = client.validate_vat("ESA28015865", trader_name="Telefonica")

result.vat_details.trader_name_match         # "MATCH" | "MISMATCH" | "NOT_AVAILABLE"
result.vat_details.trader_name_match_source  # "VERIFNOW" | "VIES"

Who compares depends on the member state. Where VIES publishes the holder's name (most of them), VerifNow compares, ignoring case, accents, punctuation and legal forms. Spain publishes no name but has VIES check one. Germany does neither, and the answer is NOT_AVAILABLE rather than a guess. A MISMATCH is a question for a human, not proof of fraud.

When your account has its own VAT number configured, vat_details.consultation_number carries the receipt VIES issues for the lookup: the evidence a tax authority accepts that you checked.

Per-country VIES availability is public and needs no API key: GET /api/v1/status/vies.

VAT rates

The rates of the 27 member states, retrieved daily from the Commission's TEDB. Public reference data: these calls spend no quota.

france = client.vat_rate("FR")  # GR is accepted for Greece (EL)

france.standard_rate   # 20.0
france.reduced_rates   # (2.1, 5.5, 10.0) — which one applies depends on the product
france.regional_rates  # (RegionalVatRate(rate=8.5, note='…Martinique…', eu_vat_area=False), …)
france.situation_on    # "2026-07-01" — the date TEDB says these rates apply from
france.fetched_at      # datetime — when VerifNow last retrieved them

every_state = client.vat_rates().rates

eu_vat_area=False marks the Canary Islands and the French overseas territories, which the VAT Directive excludes: goods shipped there from another member state are an export.

These are the rates a member state has, not the rate an invoice carries. In B2B trade between member states the invoice is usually zero-rated under the reverse charge, whatever the buyer's country rate is. Multiplying an amount by the buyer's standard rate is wrong in exactly the case a VAT number is collected for.

Validators

client.validate_email("user@example.com")
client.validate_phone("+33612345678")           # country code required
client.validate_iban("FR7630006000011234567890189")
client.validate_vat("FR12345678901")
client.validate_nas("046454286")                # Canadian Social Insurance Number
client.validate_ssn(form["ssn"])                # US Social Security Number — never commit a real one
client.validate_nif("B12345674")                # Spanish NIF — DNI, NIE or company

# When the rule is only known at runtime
client.validate("iban", value)

Every call returns the same frozen ValidationResult:

Field
valid bool
message human-readable explanation
normalized_value canonical form (E.164 for a phone), None when invalid
original_value the value as submitted
validation_level "BASIC", "STANDARD", "ADVANCED" or "PREMIUM"
email_details email only — risk score, deliverability, signals
vat_details VAT only — registration, source, trader name and match
phone_details phone only — country, line type, formats
iban_details IBAN only — structure, checksum and SEPA scope
nas_details Canadian SIN only — temporary resident, series
nif_details Spanish NIF only — DNI, NIE or company, legal form
ssn_details US SSN only — whether the number is an ITIN
quota counters from the X-RateLimit-* headers
raw the untouched response body

Enumerated values are plain strings typed with Literal, so your type checker knows them and a value a newer API adds does not break parsing.

Email signals and your plan

Email validation returns a per-signal breakdown. Which signals are present depends on your plan, so branch on applied_level rather than assuming a field is set:

Signal STANDARD (Free, Starter) ADVANCED (Growth) PREMIUM (Pro)
syntax_valid, mx_valid ✅ ✅ ✅
typo_detected, suggested_domain ✅ ✅ ✅
role_based, disposable ✅ ✅ ✅
risk_score (0–100), deliverability ✅ ✅ ✅
free_provider, domain_age_days ❌ ✅ ✅
mx_provider, mx_quality_score ❌ ✅ ✅
risk_level (LOW/MEDIUM/HIGH) ❌ ✅ ✅

A signal the applied level does not compute is None, never False.

Error handling

This SDK raises when it cannot reach the API. It never reports an unverified value as valid. A validation client that swallows an outage and answers valid=True turns downtime into silently accepted bad data, and you find out months later. Deciding to accept input during an outage is reasonable — it should just be your decision, written down:

from verifnow import (
    VerifNowAuthError,
    VerifNowConnectionError,
    VerifNowRateLimitError,
)

try:
    return client.validate_email(email).valid
except VerifNowAuthError:
    raise                           # misconfiguration — fix it, do not degrade
except VerifNowRateLimitError as error:
    log.warning("VerifNow quota exhausted until %s", error.quota and error.quota.reset_at)
    return True                     # deliberate: accept rather than block signups
except VerifNowConnectionError:
    log.exception("VerifNow unreachable, accepting unverified")
    return True
Exception Raised on Retried
VerifNowRequestError 400 / 404 — malformed payload, empty value, unknown country no
VerifNowAuthError 401 / 403 — key missing, invalid or revoked no
VerifNowRateLimitError 429 — monthly quota or concurrency limit only if the reset is imminent
VerifNowServerError 5xx yes
VerifNowConnectionError DNS, TLS, refused connection, timeout yes
VerifNowResponseError 2xx with an unparseable body no

All inherit from VerifNowError and carry status and request_id where available — quote the request id in a support request. VerifNowRateLimitError adds quota and retry_after (seconds).

Quota

Every successful response carries the quota counters:

quota = client.validate_email(email).quota

quota.remaining  # 187
quota.limit      # 250
quota.reset_at   # datetime (UTC) — start of the next billing period
quota.overage    # True once you are billed per unit

Paid plans are never cut off: past the included quota, extra requests are billed per unit and overage flips to True. The Free plan blocks at its limit with a 429.

asyncio

AsyncVerifNow has the same methods, awaitable:

from verifnow import AsyncVerifNow

client = AsyncVerifNow()

result = await client.validate_vat("IE6388047V", trader_name="Google Ireland")

Each call runs in a worker thread (asyncio.to_thread), which keeps the SDK free of an async HTTP dependency and never blocks your event loop, retries included.

Configuration

from verifnow import RetryPolicy, VerifNow

client = VerifNow(
    "vn_...",                              # default: the VERIFNOW_API_KEY environment variable
    base_url="https://api.verifnow.io",    # default
    timeout=5.0,                           # default, seconds, per attempt
    retry=RetryPolicy(
        attempts=2,                        # default — up to 3 requests in total
        backoff=0.2,                       # default, seconds, doubles each attempt
        max_backoff=2.0,                   # default
    ),
    headers={"X-Trace-Id": trace_id},      # added to every request
)

client.validate_email(email, timeout=1.0)  # per-call override

Pass retry=None to disable retries. The transport argument replaces the built-in urllib transport — a callable taking an HttpRequest and returning an HttpResponse — for tests, or to route calls through your own HTTP client.

Validating at the edge of your app

Validate on the server, where data enters — not in the browser, which would expose your API key and can be bypassed:

# FastAPI
from fastapi import FastAPI, HTTPException
from verifnow import AsyncVerifNow, VerifNowError

app = FastAPI()
verifnow = AsyncVerifNow()

@app.post("/signup")
async def signup(email: str) -> dict[str, bool]:
    try:
        result = await verifnow.validate_email(email)
    except VerifNowError:
        await create_account(email, verified=False)  # accept rather than block the signup
        return {"ok": True}

    if not result.valid:
        signals = result.email_details.signals if result.email_details else None
        raise HTTPException(422, {
            "error": result.message,
            "suggestion": signals.suggested_domain if signals else None,
        })

    await create_account(result.normalized_value, verified=True)  # store the canonical form
    return {"ok": True}

Other SDKs

Documentation

License

Apache-2.0

Metadata

Release files for verifnow 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for verifnow 0.1.0
File Size Uploaded Provenance Actions
verifnow-0.1.0.tar.gz 30.8 kB With provenance Details for verifnow-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for verifnow 0.1.0
File Interpreter ABI Platform Actions
verifnow-0.1.0-py3-none-any.whl Python 3 none any Details for verifnow-0.1.0-py3-none-any.whl

Total release size: 56.8 kB

Release files / verifnow-0.1.0.tar.gz

Download URL verifnow-0.1.0.tar.gz
Size 30.8 kB
Tags Source
SHA-256 checksum
How to use checksums
c1d1832e34e25e8d607f962000028c9e16a573d35bbdbaa09e198a8d29814b41
BLAKE2b-256 checksum
How to use checksums
aaa0b0e947feacb73e6f5276ed4c6c3e94114645d7a392c538741bcaa99bc0fd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / verifnow-0.1.0-py3-none-any.whl

Download URL verifnow-0.1.0-py3-none-any.whl
Size 26.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
80d99796021ca8a8890d79b49f11e8de1e9af54c273de3563961f5998b1fb7bd
BLAKE2b-256 checksum
How to use checksums
66bea72cdf16e984b83d4324db58573131257d14c5ec777afda1da6c3c77e492
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for verifnow 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for verifnow-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page