PAN Comprehensive

Endpoint Overview

POST /api/v1/pan/pan-comprehensive

Description

The PAN Comprehensive API provides detailed information about an individual based on their Permanent Account Number (PAN) card. This endpoint retrieves a comprehensive profile including personal details, address information, contact data, and PAN card status. The API verifies the PAN's authenticity and returns structured data that can be used for identity verification, KYC processes, and user onboarding workflows.

Key Benefits

Complete Identity Verification: Access comprehensive personal and address details linked to a PAN card in a single API call

Aadhaar Linkage Verification: Confirm whether the PAN is linked to Aadhaar, enhancing verification reliability

Structured Address Data: Receive address information in both parsed components and full format for flexible integration

Gender and Category Information: Obtain demographic details useful for analytics and personalization

Use Cases

Financial Services

Insurance

FinTech

Streamline customer onboarding for banking and financial institutions

Verify customer identity during loan application processing

Automate KYC verification for investment accounts and trading platforms

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

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

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

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication (JWT format)
Content-Type	Yes	Application/json

Request Body

Parameter	Type	Required	Description
id_number	String	Yes	PAN Card number to be verified (e.g., "EKRPR1234F")
get_address	Boolean	No	Get Address details

Example Request

{
    "id_number": "EKRPR1234F"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for all PAN-related information
data.client_id	String	Unique identifier for the API request
data.pan_number	String	PAN Card number that was verified
data.full_name	String	Complete name of the PAN holder
data.full_name_split	Array	Name broken into components [First, Middle, Last]
data.masked_aadhaar	String	Partially masked Aadhaar number linked to the PAN
data.address	Object	Structured address information (see details below)
data.email	String	Email address of the PAN holder
data.phone_number	String	Contact number of the PAN holder
data.gender	String	Gender of the PAN holder (M/F/O)
data.dob	String	Date of birth in YYYY-MM-DD format
data.input_dob	String	Date of birth provided in the input (if any)
data.aadhaar_linked	Boolean	Whether the PAN is linked to Aadhaar
data.dob_verified	Boolean	Whether the date of birth has been verified
data.dob_check	Boolean	Result of date of birth verification check
data.category	String	Category of the PAN (person, company, etc.)
data.less_info	Boolean	Indicates if limited information is available
status_code	Integer	HTTP status code of the response
success	Boolean	Whether the API call was successful
message	String	Additional information about the response (if any)
message_code	String	Code indicating the status of the response

Address Object Parameters

Parameter	Type	Description
line_1	String	House/building number and name
line_2	String	Colony/society name
street_name	String	Street or road name
zip	String	Postal/PIN code
city	String	City name
state	String	State name
country	String	Country name
full	String	Complete address as a single string

Example Successful Response

{
    "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"
}

Possible Error Responses

Invalid PAN

Authentication Error

{
    "data": null,
    "status_code": 422,
    "message": "Invalid PAN",
    "success": false
}

The provided PAN number does not match the required format or contains invalid characters.

Integration Best Practices

Security Recommendations

Store PAN data securely with appropriate encryption at rest and in transit

Implement proper access controls to limit who can access PAN verification results

Do not store the complete PAN number in client-side applications or logs

Implement rate limiting to prevent abuse of the API

User Experience Guidelines

Validate PAN format client-side before making API calls to improve user experience

Provide clear error messages to users when PAN verification fails

Consider implementing progressive disclosure of information based on verification status

Use the structured address components to auto-fill forms and improve data accuracy

Code Samples

cURL

Python

Node.js

Related APIs

PAN Basic Verification: Provides basic verification of PAN card details

PAN OCR: Extracts information from PAN card images

PAN to Aadhaar Linking Status: Checks if a PAN is linked to Aadhaar without revealing comprehensive details

PAN History: Retrieves historical verification records for a PAN

Compliance and Legal Considerations

The use of PAN data is subject to regulatory requirements in India. Ensure you have appropriate consent from users before verifying their PAN details. The data should be used only for legitimate business purposes such as KYC verification, identity validation, or fraud prevention. Storage of PAN data must comply with data protection regulations and information security standards.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/pan/pan-comprehensive' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "id_number": "EKRPR1234F" }'

{ "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" }

PAN Comprehensive

PAN Comprehensive#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Address Object Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

PAN Comprehensive

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Address Object Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples