# Mobile_Identity_Match_V1 — Mobile-to-PAN Identity API

**Mobile_Identity_Match_V1** · version `v1` · status `live`

## 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

| Method | Path | Full URL | Timeout |
| --- | --- | --- | --- |
| `POST` | `/mobile-identity-match/v1` | `https://api.pehchaantech.com/mobile-identity-match/v1` | 30000 ms |

Rate limit: **60 requests/minute** · **100000 requests/day**, counted per API key.

## 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

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

## Response example

```json
{
  "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. |

## 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. |

## 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).

---

_Generated from the pehchaantech developer portal · canonical page: https://docs.pehchaantech.com/docs/mobile-identity-match-v1 · last updated: 2026-07-26T14:31:47.019Z._