PAN Comprehensive

Endpoint Overview

POST /api/v1/pan/pan-comprehensive

Description

The PAN Comprehensive Verification API provides a complete suite of information retrieval and verification for Indian Permanent Account Number (PAN) cards. This endpoint delivers extensive details including personal information, Aadhaar linkage status, contact details, and address information associated with a PAN number.

This API goes beyond basic PAN verification by offering comprehensive data extraction, making it ideal for thorough KYC (Know Your Customer) processes, identity verification workflows, and due diligence procedures. The endpoint supports flexible masked Aadhaar variants, allowing you to retrieve masked Aadhaar information in different formats based on your specific requirements.

Key Benefits

Complete Profile Retrieval: Access full name, DOB, gender, contact details, and complete address information in a single API call

Aadhaar Linkage Verification: Instantly verify if a PAN is linked to Aadhaar and retrieve masked Aadhaar numbers

Flexible Data Formats: Support for multiple masked Aadhaar variants (v1, v2, empty, or combinations) to meet different compliance requirements

Structured Address Data: Receive both granular address components and full formatted address strings for easy integration

Use Cases

Financial Services

E-Commerce & Fintech

Insurance & Healthcare

Digital Account Opening: Streamline customer onboarding by retrieving comprehensive PAN details for account setup

Loan Application Processing: Verify applicant identity and collect necessary KYC information in real-time

Credit Assessment: Gather verified personal and contact information for credit evaluation workflows

Aadhaar-PAN Linkage Compliance: Ensure regulatory compliance by verifying Aadhaar linkage status

Masked Aadhaar Variant Configuration

The masked_aadhaar_variant parameter allows you to control how the API retrieves masked Aadhaar information. Understanding the behavior of different variant values is crucial for implementing reliable integrations.

Variant Behavior Summary

Variant Value	Behavior	Format Returned	Reliability
Not provided	Uses v1 source only (default)	XXXXXXXX1234	May fail for some PANs
"v1"	Uses v1 source only	XXXXXXXX1234	May fail for some PANs
"v2"	Uses v2 source only	12XXXXXXXX34	More reliable
"v1, v2"	Tries v1 first, then v2	Either format	Good reliability
"v2, v1"	Tries v2 first, then v1	Either format	Good reliability
"v1, v2, empty"	Tries v1, then v2, then empty fallback	Either format or ""	Best reliability (never fails)
"empty"	Skips Aadhaar fetch entirely	"" (empty string)	Always succeeds
"null"	Same as empty	null (Null Value)	Always succeeds

Variant Selection Guide

Maximum Reliability

Specific Format Required

Flexible Format

Skip Aadhaar

Recommended Value: "v1, v2, empty"

{
    "id_number": "EKRPR1234F",
    "masked_aadhaar_variant": "v1, v2, empty"
}

When to Use:

Production environments where request failures must be minimized

Critical user flows (account opening, loan applications)

When you need guaranteed API response regardless of Aadhaar availability

Behavior: Attempts to fetch from v1 source, falls back to v2 if unavailable, and returns empty string if neither source has data. This ensures the API never fails due to Aadhaar unavailability.

Understanding Format Differences

The two masked Aadhaar formats differ in their masking pattern:

v1 Format: XXXXXXXX1234

Masks the first 8 digits

Shows the last 4 digits

Example: XXXXXXXX5678

v2 Format: 12XXXXXXXX34

Shows the first 2 digits

Masks the middle 8 digits

Shows the last 2 digits

Example: 12XXXXXXXX78

Important Notes

Comma-Separated Values: When using multiple variants, separate them with commas (e.g., "v1, v2, empty")

Order Matters: The API tries variants in the order specified. Put your preferred format first.

Production Recommendation: Use "v1, v2, empty" for production environments to ensure maximum reliability

Format Consistency: Your application should be prepared to handle either format when using fallback variants

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer <YOUR_JWT_TOKEN>.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.app

Production: https://kyc-api.surepass.app

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for API authentication. Format: `Bearer <JWT_TOKEN>`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
id_number	string	Yes	Valid PAN number to be verified (e.g., "EKRPR1234F"). Must be a 10-character alphanumeric string following PAN format.
masked_aadhaar_variant	string	No	Specifies the masked Aadhaar format(s) to retrieve. Default is "v1". Options include: "v1", "v2", "null", "empty", or comma-separated combinations like "v1, v2, empty". See Masked Aadhaar Variant Configuration section for detailed behavior.

Example Request (Default)

{
    "id_number": "EKRPR1234F",
    "masked_aadhaar_variant": "v1"
}

Example Request (Maximum Reliability)

{
    "id_number": "EKRPR1234F",
    "masked_aadhaar_variant": "v1, v2, empty"
}

Example Request (Skip Aadhaar)

{
    "id_number": "EKRPR1234F",
    "masked_aadhaar_variant": "empty"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object holding all PAN verification data
data.client_id	string	Unique identifier for this verification request
data.pan_number	string	The verified PAN number
data.full_name	string	Complete name as registered with the PAN
data.full_name_split	array	Name split into components [First Name, Middle Name, Last Name]
data.masked_aadhaar	string	Masked Aadhaar number linked to the PAN. Format depends on variant used: "XXXXXXXX1234" (v1) or "12XXXXXXXX34" (v2) or "" (empty)
data.address	object	Complete address information object
data.address.line_1	string	First line of the address
data.address.line_2	string	Second line of the address
data.address.street_name	string	Street name or locality
data.address.zip	integer	PIN/ZIP code
data.address.city	string	City name
data.address.state	string	State name
data.address.country	string	Country name
data.address.full	string	Complete formatted address string
data.email	string	Masked email address associated with the PAN
data.phone_number	string	Masked phone number associated with the PAN
data.gender	string	Gender (M for Male, F for Female, O for Others)
data.dob	string	Date of birth in YYYY-MM-DD format
data.input_dob	string/null	Date of birth if provided in the request (null if not provided)
data.aadhaar_linked	boolean	Indicates whether PAN is linked to Aadhaar (true/false)
data.dob_verified	boolean	Indicates if date of birth has been verified
data.dob_check	boolean	Indicates if DOB check was performed
data.category	string	Category of PAN holder (e.g., "person", "company")
data.less_info	boolean	Indicates if limited information is available
status_code	integer	HTTP status code of the response
success	boolean	Indicates whether the API call was successful
message	string/null	Additional message or error description (null on success)
message_code	string	Status message code (e.g., "success")

Example Successful Response (v1 Format)

{
    "data": {
        "client_id": "pan_comprehensive_NZAOcvheHYtwohtkWQbH",
        "pan_number": "EKRPR1234F",
        "full_name": "MR. RATHORE",
        "full_name_split": [
            "MR",
            "",
            "RATHORE"
        ],
        "masked_aadhaar": "XXXXXXXX1234",
        "address": {
            "line_1": "A 000 ",
            "line_2": "Jagatpura",
            "street_name": "S.O",
            "zip": 123456,
            "city": "Jaipur",
            "state": "RAJASTHAN",
            "country": "INDIA",
            "full": "A 000 RAJASTHAN INDIA"
        },
        "email": "RA*********RE@GMAIL.COM",
        "phone_number": "12XXXXXX10",
        "gender": "M",
        "dob": "0001-07-00",
        "input_dob": null,
        "aadhaar_linked": true,
        "dob_verified": false,
        "dob_check": false,
        "category": "person",
        "less_info": false
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Example Successful Response (v2 Format)

{
    "data": {
        "client_id": "pan_comprehensive_XYZabcdefGHIjklmnoPQR",
        "pan_number": "EKRPR1234F",
        "full_name": "MR. RATHORE",
        "full_name_split": [
            "MR",
            "",
            "RATHORE"
        ],
        "masked_aadhaar": "12XXXXXXXX34",
        "address": {
            "line_1": "A 000 ",
            "line_2": "Jagatpura",
            "street_name": "S.O",
            "zip": 123456,
            "city": "Jaipur",
            "state": "RAJASTHAN",
            "country": "INDIA",
            "full": "A 000 RAJASTHAN INDIA"
        },
        "email": "RA*********RE@GMAIL.COM",
        "phone_number": "12XXXXXX10",
        "gender": "M",
        "dob": "0001-07-00",
        "input_dob": null,
        "aadhaar_linked": true,
        "dob_verified": false,
        "dob_check": false,
        "category": "person",
        "less_info": false
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Example Response (Empty Variant)

{
    "data": {
        "client_id": "pan_comprehensive_ABCdefghIJKlmnopQRST",
        "pan_number": "EKRPR1234F",
        "full_name": "MR. RATHORE",
        "full_name_split": [
            "MR",
            "",
            "RATHORE"
        ],
        "masked_aadhaar": "",
        "address": {
            "line_1": "A 000 ",
            "line_2": "Jagatpura",
            "street_name": "S.O",
            "zip": 123456,
            "city": "Jaipur",
            "state": "RAJASTHAN",
            "country": "INDIA",
            "full": "A 000 RAJASTHAN INDIA"
        },
        "email": "RA*********RE@GMAIL.COM",
        "phone_number": "12XXXXXX10",
        "gender": "M",
        "dob": "0001-07-00",
        "input_dob": null,
        "aadhaar_linked": true,
        "dob_verified": false,
        "dob_check": false,
        "category": "person",
        "less_info": false
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Possible Error Responses

Authentication Error

{
    "data": null,
    "status_code": 401,
    "success": false,
    "message": "Invalid or expired authentication token",
    "message_code": "unauthorized"
}

Returned when the Bearer token is missing, invalid, or expired.

Integration Best Practices

Security Recommendations

Secure Token Storage: Never expose JWT tokens in client-side code or version control systems. Store tokens securely using environment variables or secure vaults.

Use HTTPS Only: Always make API calls over HTTPS to ensure data encryption in transit.

Implement Token Rotation: Regularly rotate your JWT tokens and implement token refresh mechanisms.

Data Minimization: Only request and store the data you absolutely need for your use case.

Sensitive Data Handling: PAN data is considered sensitive personal information. Implement appropriate encryption for data at rest and comply with data protection regulations.

IP Whitelisting: Configure IP whitelisting in your Surepass account for an additional layer of security.

Masked Aadhaar Format Handling: Implement flexible parsing logic to handle both v1 and v2 masked Aadhaar formats when using fallback variants.

User Experience Guidelines

Clear Error Messages: Provide user-friendly error messages when PAN verification fails, guiding users on how to correct input errors.

Loading Indicators: Display appropriate loading states during API calls as verification may take a few seconds.

Auto-Fill Forms: Leverage the comprehensive data returned to auto-populate user forms, reducing manual data entry.

Data Validation: Implement client-side PAN format validation before making API calls to reduce unnecessary requests.

Privacy Transparency: Inform users about what data is being collected and how it will be used before initiating verification.

Masked Data Display: When displaying sensitive information like email and phone numbers, maintain the masking format received from the API.

Graceful Degradation: If using "v1, v2, empty" variant and receiving an empty masked_aadhaar, handle the UI gracefully without disrupting the user flow.

Code Samples

cURL

Python

Node.js

Related APIs

PAN Basic Verification: Quick PAN validation and status check without comprehensive details

PAN to Aadhaar Link Status: Dedicated endpoint to check only the Aadhaar linkage status

PAN Advance Verification: Enhanced verification with additional data points and validation checks

Aadhaar Verification API: Verify Aadhaar details and link them with PAN information

Compliance and Legal Considerations

Data Privacy: This API handles sensitive personal information. Ensure compliance with India's Personal Data Protection regulations and obtain proper user consent before verification.

UIDAI Guidelines: Masked Aadhaar retrieval must comply with UIDAI (Unique Identification Authority of India) guidelines for Aadhaar data handling.

KYC Regulations: Usage must align with RBI's KYC guidelines and Prevention of Money Laundering Act (PMLA) requirements.

Data Retention: Implement appropriate data retention policies as per regulatory requirements. Do not store PAN data longer than necessary.

Audit Trail: Maintain logs of all PAN verification requests for compliance and audit purposes.

Purpose Limitation: Use PAN data only for the specific purpose disclosed to and consented by the user.

Aadhaar-PAN Linkage: As per Income Tax regulations, PAN-Aadhaar linkage is mandatory. The aadhaar_linked field helps ensure compliance with this requirement.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

PAN Comprehensive

PAN Comprehensive#

Description#

Use Cases#

Masked Aadhaar Variant Configuration#

Variant Behavior Summary#

Variant Selection Guide#

Understanding Format Differences#

Technical Implementation#

Request Headers#

Request Body#

Example Request (Default)#

Example Request (Maximum Reliability)#

Example Request (Skip Aadhaar)#

Response Parameters#

Example Successful Response (v1 Format)#

Example Successful Response (v2 Format)#

Example Response (Empty Variant)#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

PAN Comprehensive

Description

Use Cases

Masked Aadhaar Variant Configuration

Variant Behavior Summary

Variant Selection Guide

Understanding Format Differences

Technical Implementation

Request Headers

Request Body

Example Request (Default)

Example Request (Maximum Reliability)

Example Request (Skip Aadhaar)

Response Parameters

Example Successful Response (v1 Format)

Example Successful Response (v2 Format)

Example Response (Empty Variant)

Possible Error Responses

Integration Best Practices

Code Samples