Quickstart

Log in to your 9thSense dashboard and create an API key from Settings → API Keys. Keys use the format zk_<prefix>_<secret>.

Set it as an environment variable:

export NINTHSENSE_API_KEY="zk_live_your_key_here"

Pass it as the X-Api-Key header on every request. All endpoints require authentication.

The PyPI package is 9thsense. The import name is ninthsense — Python module names cannot start with a digit.

pip install 9thsense

Verify the install:

python -c "import ninthsense; print(ninthsense.__version__)"

The kyc_pan_card document type extracts 7 fields. Here is its output schema exactly as configured in the platform:

pan_number      string — 10-character alphanumeric
name            string
father_name     string or null
date_of_birth   YYYY-MM-DD or null
pan_type        string or null — Individual (P), Company (C), HUF (H), Trust (T) etc.
photo_present   boolean
signature_present boolean or null

import asyncio
import os
from ninthsense import Client

async def verify_pan(image_url: str) -> dict:
    async with Client(
        api_key=os.environ["NINTHSENSE_API_KEY"],
        base_url="https://api.9thsense.ai",
    ) as client:
        result = await client.verify.document(
            file_url=image_url,
            doc_type="kyc_pan_card",
        )
        result.raise_on_error()
        return result.extracted

output = asyncio.run(verify_pan("https://example.com/pan_card.jpg"))
print(output)

curl -X POST https://api.9thsense.ai/v1/verify \
  -H "X-Api-Key: $NINTHSENSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "doc_type": "kyc_pan_card",
    "file_url": "https://example.com/pan_card.jpg"
  }'

To upload a file directly instead of passing a URL, use multipart/form-data:

curl -X POST https://api.9thsense.ai/v1/verify \
  -H "X-Api-Key: $NINTHSENSE_API_KEY" \
  -F "doc_type=kyc_pan_card" \
  -F "file=@/path/to/pan_card.jpg"

Accepted formats: PDF, JPEG, PNG, TIFF, WEBP, BMP. Maximum file size: 50 MB.

A successful verification returns a VerifyResult with success: true, the structured fields in extracted, and the verdicts of every check and goal rule that ran:

{
  "success": true,
  "extracted": {
    "pan_number": "ABCDE1234F",
    "name": "Priya Sharma",
    "father_name": "Rajesh Sharma",
    "date_of_birth": "1990-05-15",
    "pan_type": "P",
    "photo_present": true,
    "signature_present": true
  },
  "checks": [
    { "name": "document_integrity", "verdict": "pass", "confidence": 0.98 }
  ],
  "rules": [
    { "rule_id": "pan_checksum_valid", "passed": true, "severity": "hard_stop" }
  ],
  "latency_ms": 1240,
  "from_self_hosted": false
}

Notice that you did not just get the fields — the PAN number's checksum was validated and the document was screened for tampering and synthesis, automatically. That is the core of the platform: see Checks and Goal Rules.

If verification fails, success is false and error contains the reason. In Python, calling .raise_on_error() on the result throws a VerificationError so you can handle it cleanly:

from ninthsense.models import VerificationError

try:
    result = await client.verify.document(
        file_url=image_url,
        doc_type="kyc_pan_card",
    )
    result.raise_on_error()
    data = result.extracted
except VerificationError as e:
    print(f"Verification failed: {e.message}")

You have a working extraction call. Here is where to go from here:

Add fraud checks. Extraction tells you what the document says; checks tell you whether to believe it — liveness, deepfake detection, face match, synthetic-document detection, and cross-verification, all gated by Goal Rules.

Try other document types. The platform has 40+ pre-built document types. Swap kyc_pan_card for any context_id — for example fin_bank_statement, kyc_aadhaar, biz_gst_certificate, or travel_passport. See the Document Type Library for the full list.

Build an agent. Agents orchestrate a full verification workflow — collect documents, extract fields, run checks, evaluate Goal Rules, and deliver a webhook — from a single JSON definition. See Build a KYC Agent.

Explore face search. If your workflow includes a selfie, the platform handles 1:1 match against the ID photo or 1:N search across your enrolled biometric databases. See Face Search.

Read the SDK docs. The Python SDK has typed models, async-first design, and a .raise_on_error() pattern for clean error handling. See Python SDK.