PAN_Lookup_By_Mobile_V1 — PAN Lookup by Mobile API

PAN_Lookup_By_Mobile_V1 v1 live

Download as Markdownthe full page as a single .md file — for offline reading or as context for an AI assistant

Authentication

Every request must carry your API key in the X-API-Key header. Your key is issued to you separately by ops and is never shown in this document.

X-API-Key: <your-key>

Base URL

All endpoints are served through the gateway:

https://api.pehchaantech.com

Endpoints

POST /pan-lookup-by-mobile/v1

URL	`https://api.pehchaantech.com/pan-lookup-by-mobile/v1`
Timeout	30000 ms
Rate limit	60 req/min · 100000 req/day

Overview

Retrieve the PAN (Permanent Account Number) and the registered name linked to a mobile number. One call, two fields — built for onboarding prefill where you need the PAN and nothing else.

Need date of birth, gender, income bracket, addresses, emails or alternate phone numbers as well? That is a different API — POST /mobile-identity-match/v1 returns the full identity profile. Only the result object differs between the two, so switching is a one-line change. They are separate, separately billed lookups — calling both for the same number is two charges.

mobile_number and consent_declaration are the ONLY accepted fields. consent_declaration must exactly equal the required attestation text (see field descriptions below) — it is YOUR confirmation that you obtained the individual’s consent before looking them up, and is checked before any lookup happens, so a missing/wrong value costs nothing.

Every response — success or not — uses the same envelope, so branch on the status field. There is NO pending state; every response is final. Latency is capped at 30 seconds, so set your client timeout to at least 35 seconds.

BILLING: completed and not_found are both billable — the source was actually queried either way. invalid_input is NOT billable — a rejected number never reached the source. Validate numbers before calling (a malformed number is rejected with 422 and costs nothing), don’t loop on not_found, and de-duplicate — two calls for the same number are two charges.

Request example

{
  "mobile_number": "9876543210",
  "client_ref_num": "onboard-7f3a2b",
  "consent_declaration": "I take consent to collection and processing of data"
}

Response example

{
  "result": {
    "full_name": "ROHIT KUMAR SHARMA",
    "pan_number": "BXXXXXXXXL",
    "pan_enrichment_data": {
      "data": {
        "name": "ROHIT KUMAR SHARMA",
        "gender": "MALE",
        "date_of_birth": "1999-01-01",
        "document_type": "PAN"
      },
      "enrichment_level": "ESSENTIALS"
    }
  },
  "status": "completed",
  "success": true,
  "description": "PAN retrieved successfully",
  "client_ref_num": "pehchaan-b5f08841d8f1"
}

Fields

Field Description

mobile_number Required. 10-digit Indian mobile number, first digit 6-9 (^[6-9]\d{9}$).

consent_declaration Required. Must exactly equal "I take consent to collection and processing of data" — your attestation that you obtained the mobile number owner’s consent. Not forwarded to the source. A missing or incorrect value is a free 422, before any lookup.

client_ref_num Optional trace id; 6–64 chars of A-Z a-z 0-9 . _ -. Omit and the platform generates one. Each call is an independent lookup, so use a FRESH value per attempt. Also returned in the X-Client-Ref-Num response header.

success true only when a PAN was delivered.

status Machine-readable outcome — branch on this (see Outcomes below).

result The PAN record — present only when status = completed, otherwise null. Contains pan_number (the PAN linked to this mobile number) and full_name (the name registered against that PAN). Treat it as an OPEN structure: a field can be empty or absent when the source has no data for it, and new fields may appear without notice. Read the paths you need defensively rather than validating against a fixed schema.

Field	Description
`mobile_number`	Required. 10-digit Indian mobile number, first digit 6-9 (^[6-9]\d{9}$).
`consent_declaration`	Required. Must exactly equal "I take consent to collection and processing of data" — your attestation that you obtained the mobile number owner’s consent. Not forwarded to the source. A missing or incorrect value is a free 422, before any lookup.
`client_ref_num`	Optional trace id; 6–64 chars of A-Z a-z 0-9 . _ -. Omit and the platform generates one. Each call is an independent lookup, so use a FRESH value per attempt. Also returned in the X-Client-Ref-Num response header.
`success`	true only when a PAN was delivered.
`status`	Machine-readable outcome — branch on this (see Outcomes below).
`result`	The PAN record — present only when status = completed, otherwise null. Contains pan_number (the PAN linked to this mobile number) and full_name (the name registered against that PAN). Treat it as an OPEN structure: a field can be empty or absent when the source has no data for it, and new fields may appear without notice. Read the paths you need defensively rather than validating against a fixed schema.

Errors

Code Meaning

completed (HTTP 200) — BILLABLE PAN delivered in result — consume it.

not_found (HTTP 200) — BILLABLE "No PAN found for this mobile number" — no PAN is linked to this number. Definitive; do NOT retry. Billed the same as a successful lookup, because the source was actually queried.

invalid_input (HTTP 200) — not billable "Invalid mobile number" — the number was rejected by the source before any query ran. Re-check the number with the customer; do NOT retry unchanged.

failed (HTTP 502) — not billable "Source down — please retry later." Temporary upstream issue and the ONLY retryable status; retry with exponential backoff (~2 s, max 3 tries). Free, because the source never answered.

401 / 403 Missing or invalid API key, or the key is not granted this API.

422 Validation failed — malformed mobile number, missing/incorrect consent_declaration, or a field outside the contract. Never retry unchanged.

429 Rate limited — respect the Retry-After header.

503 / 504 Gateway protecting itself, or the call exceeded the 30 s budget — retry.

Code	Meaning
`completed (HTTP 200) — BILLABLE`	PAN delivered in result — consume it.
`not_found (HTTP 200) — BILLABLE`	"No PAN found for this mobile number" — no PAN is linked to this number. Definitive; do NOT retry. Billed the same as a successful lookup, because the source was actually queried.
`invalid_input (HTTP 200) — not billable`	"Invalid mobile number" — the number was rejected by the source before any query ran. Re-check the number with the customer; do NOT retry unchanged.
`failed (HTTP 502) — not billable`	"Source down — please retry later." Temporary upstream issue and the ONLY retryable status; retry with exponential backoff (~2 s, max 3 tries). Free, because the source never answered.
`401 / 403`	Missing or invalid API key, or the key is not granted this API.
`422`	Validation failed — malformed mobile number, missing/incorrect consent_declaration, or a field outside the contract. Never retry unchanged.
`429`	Rate limited — respect the Retry-After header.
`503 / 504`	Gateway protecting itself, or the call exceeded the 30 s budget — retry.

Changelog

2026-07-26 Initial release: mobile-number-only PAN lookup with a required consent attestation field, uniform response envelope, no pending state (every response is final).