Guide · Python · SDK

Getting Started with the IsValid Python SDK

Go from zero to validated data in under five minutes. Install the official Python SDK, create a client, run your first validation, and learn how to handle errors properly.

In this guide

  1. 1. Prerequisites
  2. 2. Installation
  3. 3. Create a client
  4. 4. Your first validation
  5. 5. More examples
  6. 6. Namespaced methods
  7. 7. Country-specific validators
  8. 8. Error handling
  9. 9. Next steps

1. Prerequisites

Before you start, make sure you have:

ℹ️The free tier gives you 100 API calls per day — more than enough to follow this guide and start integrating.

2. Installation

Install the SDK from PyPI:

pip install isvalid-sdk

The package has a single dependency (httpx) and supports Python 3.9+.

3. Create a client

Import create_client and pass your API key:

from isvalid_sdk import IsValidConfig, create_client

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

That's it — you're ready to validate. The client uses sensible defaults: 10-second timeout, automatic retry with exponential backoff on 429 and 5xx errors.

You can also use the client as a context manager:

with create_client(IsValidConfig(api_key="your-api-key")) as iv:
    result = iv.email("user@example.com")

You can customize the defaults if needed:

from isvalid_sdk import IsValidConfig, RetryConfig, create_client

iv = create_client(IsValidConfig(
    api_key="your-api-key",
    timeout=15.0,           # 15 seconds (default: 10.0)
    retry=RetryConfig(
        max_retries=5,      # default: 3
        initial_delay=1.0,  # default: 0.5
        max_delay=30.0,     # default: 10.0
    ),
))

# Or disable retry entirely
iv = create_client(IsValidConfig(api_key="your-api-key", retry=None))
✅Store your API key in an environment variable (e.g. ISVALID_API_KEY) and read it with os.environ["ISVALID_API_KEY"]. Never commit API keys to version control.

4. Your first validation

Let's validate an email address with an MX record check:

result = iv.email("user@example.com", check_mx=True)
print(result)

Response:

{
  "valid": true,
  "local": "user",
  "domain": "example.com",
  "mxValid": true
}

Every response includes a valid boolean. When valid is True, you can access all returned fields. All responses are typed with TypedDict for full IDE support:

result = iv.email("user@example.com", check_mx=True)

if result["valid"]:
    print(result["domain"])   # "example.com"
    print(result["mxValid"])  # True
else:
    print("Invalid email")

5. More examples

The SDK exposes 50+ validators as simple method calls. Here are a few common ones:

IBAN

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

VAT number with VIES check

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

Phone number

phone = iv.phone("+48501234567")
# => {"valid": True, "countryCode": "PL", "callingCode": "48", "type": "MOBILE", "e164": "+48501234567", ...}

Credit card (POST endpoint)

card = iv.credit_card("4111111111111111")
# => {"valid": True, "network": "Visa"}
ℹ️See the full API documentation for all 50+ validators and their response schemas.

6. Namespaced methods

Some endpoints group related functionality under namespaces. These support both validation and data listing:

# LEI — validate, search by name, list LOUs
lei = iv.lei("7LTWFZYICNSX8D621K86")
search = iv.lei.search("Apple", country="US", limit=5)
lous = iv.lei.lous()

# Country / Currency / Language — validate or list all
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 — airports, airlines, flights
airport = iv.iata.airport("WAW")
airline = iv.iata.airline("LH")
airlines = iv.iata.airline.list()
flight = iv.iata.flight("LH1234")

7. Country-specific validators

Validators specific to a country are grouped under two-letter country code namespaces:

# 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")

# Australia
iv.au.abn("51824753556")

# Spain
iv.es.nif("12345678Z")

# India
iv.in_.gstin("27AAPFU0939F1ZV")  # note: in_ (reserved word)

# United States
iv.us.npi("1234567893")

# United Kingdom
iv.gb.sort_code("12-34-56")

8. Error handling

The SDK provides three exception classes so you can handle each failure mode separately:

from isvalid_sdk import (
    IsValidError,
    IsValidAuthError,
    IsValidRateLimitError,
)

try:
    result = iv.email("test@example.com")
except IsValidRateLimitError as e:
    # 429 — you've exceeded your daily limit
    print("Rate limited, retry after:", e.retry_after, "seconds")
except IsValidAuthError as e:
    # 401 — invalid or missing API key
    print("Invalid API key")
except IsValidError as e:
    # Other API error (4xx / 5xx)
    print("API error:", e.status, e.body["error"])
Exception classHTTP statusWhen
IsValidAuthError401Invalid or missing API key
IsValidRateLimitError429Daily call limit exceeded
IsValidError4xx / 5xxAny other API error
✅The SDK automatically retries on 429 and 5xx errors with exponential backoff (up to 3 retries by default). You only need to catch errors that persist after retries.

9. Next steps

📖

API Documentation

All 50+ endpoints with response schemas

💻

SDK on GitHub

Source code, issues, and contributions

📦

PyPI package

Version history and install stats

📚

All Guides

In-depth tutorials for specific validators

Start validating today

Free tier includes 100 API calls per day. No credit card required.

Get Free API KeyView Full API Docs