Mobile_Identity_Match_V1 — Mobile-to-PAN Identity API

Mobile_Identity_Match_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 /mobile-identity-match/v1

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

Overview

Retrieve the identity profile linked to a mobile number: PAN, name, date of birth, gender, income bracket, and known contact details (alternate phones, emails, addresses). One call returns the whole profile.

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": {
    "email": [
      {
        "value": "ROHIT.SHARMA@EXAMPLE.COM",
        "serial_number": "1"
      }
    ],
    "address": [
      {
        "state": "KA",
        "pincode": "560001",
        "detailed_address": "12 MG ROAD BENGALURU 560001 KA",
        "date_of_reporting": "2026-06-01"
      }
    ],
    "document_data": {
      "pan": [
        {
          "value": "ABCDE1234F",
          "serial_number": "1"
        }
      ]
    },
    "alternate_phone": [
      {
        "value": "9812345678",
        "serial_number": "1"
      }
    ],
    "personal_information": {
      "age": "34",
      "gender": "MALE",
      "income": "10,00,001 - 25,00,000",
      "full_name": "ROHIT KUMAR SHARMA",
      "date_of_birth": "1992-05-14"
    }
  },
  "status": "completed",
  "success": true,
  "description": "Details 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 profile was delivered.

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

result The profile — present only when status = completed, otherwise null. Contains personal_information (full_name, gender, age, date_of_birth, income), alternate_phone[], email[], address[], and document_data.pan[]. Treat it as an OPEN structure: any sub-object or array can be empty or absent, 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 profile was delivered.
`status`	Machine-readable outcome — branch on this (see Outcomes below).
`result`	The profile — present only when status = completed, otherwise null. Contains personal_information (full_name, gender, age, date_of_birth, income), alternate_phone[], email[], address[], and document_data.pan[]. Treat it as an OPEN structure: any sub-object or array can be empty or absent, 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 Profile delivered in result — consume it.

not_found (HTTP 200) — BILLABLE "No records found for this mobile number" — no identity 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`	Profile delivered in result — consume it.
`not_found (HTTP 200) — BILLABLE`	"No records found for this mobile number" — no identity 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-22 Initial release: mobile-number-only lookup with a required consent attestation field, uniform response envelope, no pending state (every response is final).