KYC Document Verification API

One-line gallery pitch:

REST API that validates Indian KYC documents (PAN / Aadhaar) — format checks, Verhoeff checksum, age eligibility, and name consistency — returning a structured risk score and verdict; drop-in backend for any NBFC / fintech onboarding flow.

---

What it does

POST /verify accepts document fields and runs a chain of validation checks:

Check	Logic
PAN format	Regex AAAAA9999A (5 alpha + 4 digit + 1 alpha, uppercase)
Aadhaar format + checksum	12-digit + Verhoeff algorithm (same used by UIDAI)
DOB / age	ISO date parse, age ≥ 18, age ≤ 120
Name consistency	Token-overlap ratio across supplied name fields

Each check contributes a weighted miss to the risk score (0.0 = clean, 1.0 = high risk). The final verdict is CLEAR / REVIEW / REJECT.

---

Quick start

pip install -r requirements.txt
uvicorn app:app --reload

Interactive docs: http://localhost:8000/docs

---

Example request

curl -s -X POST http://localhost:8000/verify \
  -H "Content-Type: application/json" \
  -d @sample_request.json | python3 -m json.tool

Request (sample_request.json):

{
  "doc_type": "PAN",
  "doc_number": "ABCDE1234F",
  "name": "Mohan Kumar",
  "dob": "1990-06-15",
  "name_on_doc": "Mohan Kumar"
}

Response:

{
  "status": "success",
  "doc_type": "PAN",
  "doc_number": "ABCDE1234F",
  "extracted_fields": {
    "name": "Mohan Kumar",
    "dob": "1990-06-15",
    "age": 35
  },
  "checks": [
    {"name": "pan_format",  "passed": true,  "detail": "PAN matches AAAAA9999A pattern"},
    {"name": "dob_age",     "passed": true,  "detail": "Age 35 — eligible"},
    {"name": "name_match",  "passed": true,  "detail": "Name token overlap 100% (OK)"}
  ],
  "risk_score": 0.0,
  "verdict": "CLEAR"
}

---

Run tests

# with pytest
pytest test_app.py -v

# or standalone (no pytest needed)
python test_app.py

---

Supported doc types

doc_type	Validated as
PAN	Format regex + name/DOB checks
AADHAAR	12-digit + Verhoeff checksum + name/DOB checks

---

What a full production version adds

This demo shows the validation pattern and API contract. A production KYC service would layer on:

• Real OCR — Tesseract / AWS Textract / Azure Form Recognizer to extract fields from uploaded images instead of accepting them as JSON input
• Bureau / NSDL integration — live PAN verification via NSDL/UTI API; Aadhaar eKYC via UIDAI or certified KUA
• Liveness check — selfie + ID comparison (face-match) via provider SDK (e.g., Aadhaar Face RD service)
• Sanctions / watchlist screening — OFAC, UN, RBI defaulter list lookups
• Encrypted at-rest storage — never store raw Aadhaar digits; store masked or hashed references only (per UIDAI circular)
• Audit trail — immutable log per verification attempt for RBI/SEBI inspection
• Rate limiting + fraud signals — velocity checks, device fingerprint, IP geo
• Webhook / async flow — POST triggers async job, result delivered to callback URL (suits slow bureau APIs)

---

Author

Built by Mohan Kumar — CTO & fintech specialist (NBFC / LOS / LMS / KYC / collections). Available for freelance engagements: Fiverr · Upwork