IndiaID 🇮🇳

IndiaID is a lightweight, zero-dependency Python library for validating, parsing, and masking Indian government IDs, identity numbers, and document codes.

Designed for FinTechs, KYC onboarding pipelines, HRMS, and modern web applications.

✨ Features

• ⚡ Zero Runtime Dependencies: Pure Python 3.9+ standard library.
• 🧮 Algorithmic Validation: Verhoeff algorithm for Aadhaar, Luhn mod-36 for GSTIN.
• 🎭 Privacy & Masking: UIDAI-compliant Aadhaar masking (XXXXXXXX1234).
• 🧩 Metadata Extraction: Parse state, entity type (PAN), issue year (DL), and circle.
• 🔌 Framework Integrations: First-class support for Pydantic v2, Django, and DRF.
• 🛡️ Fully Type-Hinted: PEP 561 compliant (py.typed) with strict typing.

📦 Installation

pip install indiaid

With optional integrations:

# With Pydantic v2 support
pip install "indiaid[pydantic]"

# With Django support
pip install "indiaid[django]"

# With all integrations
pip install "indiaid[all]"

🚀 Quickstart

1. Direct Document Imports (Most Popular)

Import document validators directly:

from indiaid import pan, aadhaar, gstin

# Validate directly (returns True / False)
pan.is_valid("ABCPE1234F")          # True
aadhaar.is_valid("3675 9834 6215")  # True (checks Verhoeff checksum)

# Or use callable shortcut
if pan("ABCPE1234F"):
    print("Valid PAN!")

# Mask for privacy / compliance
pan.mask("ABCPE1234F")              # "ABXXXXXX4F"
aadhaar.mask("3675 9834 6215")      # "XXXXXXXX6215"

2. Rich Validation & Metadata Extraction

from indiaid import validate

# Parse PAN details
result = validate("pan", "ABCPE1234F")
if result.is_valid:
    print(result.cleaned_value)       # "ABCPE1234F"
    print(result.metadata["entity_type"])  # "Individual"
    print(result.metadata["surname_initial"]) # "E"

# Parse GSTIN details
result = validate("gstin", "27ABCPE1234F1Z5")
if result.is_valid:
    print(result.metadata["state_code"])  # "27"
    print(result.metadata["state_name"])  # "Maharashtra"
    print(result.metadata["pan"])         # "ABCPE1234F"

# Vehicle State Lookup
from indiaid import vehicle
print(vehicle.state("MH01A2925"))   # "Maharashtra"
print(vehicle.state("MH"))          # "Maharashtra"
print(vehicle.state("22BH1234AA"))  # "Bharat Series (All India)"

3. Masking for Privacy Compliance

import indiaid

# Mask Aadhaar for UIDAI/RBI compliance
masked = indiaid.mask("aadhaar", "3675 9834 6215")
print(masked)  # "XXXXXXXX6215"

📑 Supported Documents

🛠️ Framework Integrations

Pydantic v2

from pydantic import BaseModel
from indiaid.integrations.pydantic import AadhaarStr, PanStr, GstinStr

class UserKYC(BaseModel):
    pan: PanStr
    aadhaar: AadhaarStr
    gstin: GstinStr

Django Models & Forms

from django.db import models
from indiaid.integrations.django import validate_pan, validate_aadhaar

class Profile(models.Model):
    pan = models.CharField(max_length=10, validators=[validate_pan])
    aadhaar = models.CharField(max_length=12, validators=[validate_aadhaar])

📄 License

MIT © IndiaID Contributors