isvalid-sdk 0.2.0

Python SDK for the isvalid.dev validation API

isvalid-sdk

Python SDK for the isvalid.dev validation API.

Features

• Single dependency — only httpx
• Full type hints with TypedDict for every endpoint response
• Context manager support for proper resource cleanup
• Automatic retry with exponential backoff for 429/5xx
• Custom exception classes for auth and rate limit errors
• Python 3.9+

Installation

pip install isvalid-sdk

Quick Start

Get your free API key at isvalid.dev/getting-started.

from isvalid_sdk import IsValidConfig, create_client

iv = create_client(IsValidConfig(api_key="your-api-key"))

# Simple validation
email = iv.email("[e-mail]", check_mx=True)
# => {"valid": True, "local": "user", "domain": "example.com", "mxValid": True}

iban = iv.iban("DE89370400440532013000")
# => {"valid": True, "countryCode": "DE", "bankName": "Commerzbank", ...}

vat = iv.vat("DE123456789", check_vies=True)
# => {"valid": True, "countryCode": "DE", "isEU": True, "vies": {"checked": True, ...}}

Context Manager

with create_client(IsValidConfig(api_key="your-api-key")) as iv:
    result = iv.email("[e-mail]")

Namespaced Methods

# LEI
lei = iv.lei("5493001KJTIIGC8Y1R12")
search = iv.lei.search("Apple", country="US", limit=5)
lous = iv.lei.lous()

# Country / Currency / Language
country = iv.country("PL")
countries = iv.country.list()

currency = iv.currency("USD")
currencies = iv.currency.list()

language = iv.language("en")
languages = iv.language.list()

# IATA
flight = iv.iata.flight("LH1234")
airline = iv.iata.airline("LH")
airlines = iv.iata.airline.list()
airport = iv.iata.airport("WAW")

Country-Specific Endpoints

# Poland
iv.pl.pesel("44051401358")
iv.pl.regon("012345678", lookup=True)
iv.pl.krs("0000123456", lookup=True)

# Brazil
iv.br.cnpj("11.222.333/0001-81")
iv.br.cpf("123.456.789-09")

# Other
iv.au.abn("51824753556")
iv.es.nif("12345678Z")
iv.in_.gstin("27AAPFU0939F1ZV")  # note: in_ (reserved word)
iv.us.npi("1234567893")
iv.gb.sort_code("12-34-56")

Network & Financial

# Network
iv.net.ip("192.168.1.1")
iv.net.mac("00:1B:44:11:3A:B7")

# Financial
iv.isin("US0378331005")
iv.dti("B1234567Z")
iv.bic("DEUTDEFF")
iv.cusip("037833100")
iv.credit_card("4111111111111111")  # POST endpoint

All Simple Endpoints

iv.email(value, check_mx=)     iv.iban(value, country_code=)
iv.isin(value)                  iv.dti(value)
iv.vat(value, country_code=, check_vies=)
iv.gps(value)                   iv.phone(value, country_code=)
iv.url(value)                   iv.ean(value)
iv.isbn(value)                  iv.issn(value)
iv.bic(value)                   iv.cusip(value)
iv.cfi(value)                   iv.mic(value)
iv.nuts(value)                  iv.uuid(value, version=)
iv.jwt(value)                   iv.vin(value)
iv.imei(value)                  iv.semver(value)
iv.color(value)                 iv.boolean(value)
iv.date(value, format=)         iv.btc_address(value)
iv.postal_code(value, country_code=)
iv.aba(value)                   iv.container_code(value)
iv.sscc(value)                  iv.gln(value)
iv.qr(value)                    iv.credit_card(number)

Configuration

from isvalid_sdk import IsValidConfig, RetryConfig, create_client

iv = create_client(IsValidConfig(
    api_key="your-api-key",
    base_url="https://api.isvalid.dev",  # default
    timeout=15.0,                         # default: 10.0 (seconds)
    retry=RetryConfig(
        max_retries=5,                   # default: 3
        initial_delay=1.0,               # default: 0.5
        max_delay=30.0,                  # default: 10.0
        retry_on=(429, 500, 502, 503),   # default
    ),
))

# Disable retry
iv = create_client(IsValidConfig(api_key="...", retry=None))

Error Handling

from isvalid_sdk import (
    IsValidError, IsValidAuthError, IsValidRateLimitError, create_client
)

try:
    iv.email("[e-mail]")
except IsValidRateLimitError as e:
    print("Rate limited, retry after:", e.retry_after, "seconds")
except IsValidAuthError as e:
    print("Invalid API key")
except IsValidError as e:
    print("API error:", e.status, e.body["error"])

API Reference

Full endpoint documentation: isvalid.dev/docs

License

MIT