PAN Comprehensive V2

Endpoint Overview

POST /api/v1/pan/pan-comprehensive-v2

Description

The PAN Comprehensive V2 API provides extensive verification and information retrieval based on an individual's Permanent Account Number (PAN). This endpoint delivers a comprehensive profile including personal details, contact information, address data, and verification statuses. The API performs real-time validation against official government databases to ensure data accuracy and reliability, making it an essential tool for robust identity verification and KYC compliance processes.

Key Benefits

Complete Identity Verification: Access comprehensive personal information including name, contact details, and address in a single API call

Enhanced Due Diligence: Verify additional statuses like sole proprietorship, directorship, and employment type

Aadhaar Linkage Verification: Confirm if the PAN is linked to Aadhaar for additional identity assurance

Simplified KYC Process: Streamline customer onboarding with reliable, government-verified data

Use Cases

Financial Services

Fintech

Insurance

Streamline customer onboarding for banking and financial institutions

Verify customer identity for loan applications and credit assessments

Conduct enhanced due diligence for high-value transactions

Validate customer information 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	The PAN (Permanent Account Number) to be verified. Must be a valid 10-character alphanumeric PAN.

Example Request

{
    "id_number": "AGYPP1234F"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains all the verification data
data.client_id	String	Unique identifier for the verification request
data.pan_number	String	The PAN number that was verified
data.pan_details	Object	Comprehensive details of the PAN holder
data.is_sole_proprietor	Boolean	Indicates if the individual is registered as a sole proprietor
data.is_director	Boolean	Indicates if the individual is registered as a company director
data.is_salaried	Boolean	Indicates if the individual is registered as a salaried employee
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the API call was successful
message	String	Human-readable status message
message_code	String	Machine-readable status code

pan_details Object

Parameter	Type	Description
full_name	String	Complete name of the PAN holder
full_name_split	Array	Name components split into individual elements
masked_aadhaar	String	Partially masked Aadhaar number if linked to the PAN
address	Object	Detailed address information
email	String	Email address of the PAN holder
phone_number	String	Contact number of the PAN holder
gender	String	Gender of the PAN holder (M/F/O)
dob	String	Date of birth in YYYY-MM-DD format
input_dob	String	Date of birth provided in the input (if any)
aadhaar_linked	Boolean	Indicates if Aadhaar is linked to the PAN
dob_verified	Boolean	Indicates if the date of birth has been verified
dob_check	Boolean	Indicates if date of birth check was performed
category	String	Category of the PAN holder (e.g., "person")
less_info	Boolean	Indicates if limited information is available

address Object

Parameter	Type	Description
line_1	String	First line of the address (building/house number)
line_2	String	Second line of the address (if available)
street_name	String	Street or locality name
zip	String	Postal/ZIP code
city	String	City name
state	String	State name
country	String	Country name
full	String	Complete formatted address as a single string

Example Successful Response

{
    "data": {
        "client_id": "pan_comprehensive_v2_teyfYScxeXbuRtbbnPqd",
        "pan_number": "ACNPR3826N",
        "pan_details": {
            "full_name": "MUNNA BHAIYA",
            "full_name_split": [
                "MUNNA",
                "BHAIYA"
            ],
            "masked_aadhaar": "XXXXXXXX1234",
            "address": {
                "line_1": "A-123",
                "line_2": "",
                "street_name": "Mirzapur",
                "zip": "302017",
                "city": "Mirzapur",
                "state": "",
                "country": "INDIA",
                "full": "A-102/3S.F.S. Mirzapur 302017 Uttarpradesh INDIA"
            },
            "email": "abhitest@gmail.com",
            "phone_number": "9878564524",
            "gender": "M",
            "dob": "1961-06-12",
            "input_dob": null,
            "aadhaar_linked": true,
            "dob_verified": false,
            "dob_check": false,
            "category": "person",
            "less_info": false
        },
        "is_sole_proprietor": true,
        "is_director": true,
        "is_salaried": true
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "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 API keys and tokens securely using environment variables or a secure vault

Implement proper error handling to avoid exposing sensitive information in error messages

Use HTTPS for all API communications to ensure data encryption in transit

Implement rate limiting on your side to prevent abuse of the API

Log API requests and responses for audit purposes, but mask sensitive PAN data in logs

User Experience Guidelines

Implement client-side validation for PAN format before making API calls

Display a loading indicator during API calls to provide feedback to users

Clearly communicate verification status to end-users with appropriate success/error messages

Cache verification results (where appropriate) to improve performance for repeat lookups

Provide clear instructions for users when verification fails, suggesting possible remediation steps

Code Samples

cURL

Python

Node.js

Related APIs

PAN Basic Verification: Simple PAN validation with minimal information

PAN Name Match: Verify if a provided name matches the name registered with a PAN

PAN OCR Verification: Extract and verify PAN details from PAN card images

PAN to Aadhaar Link Status: Check if a PAN is linked to an Aadhaar number

Compliance and Legal Considerations

This API handles Personally Identifiable Information (PII) and is subject to data protection regulations. Ensure you have proper consent from users before verifying their PAN details. The data should be used only for legitimate business purposes such as KYC verification, fraud prevention, or regulatory compliance. Storage of PAN data must comply with applicable data protection laws including but not limited to the Information Technology Act and rules framed thereunder in India.

{ "data": { "client_id": "pan_comprehensive_v2_teyfYScxeXbuRtbbnPqd", "pan_number": "ACNPR3826N", "pan_details": { "full_name": "MUNNA BHAIYA", "full_name_split": [ "MUNNA", "BHAIYA" ], "masked_aadhaar": "XXXXXXXX1234", "address": { "line_1": "A-123", "line_2": "", "street_name": "Mirzapur", "zip": "302017", "city": "Mirzapur", "state": "", "country": "INDIA", "full": "A-102/3S.F.S. Mirzapur 302017 Uttarpradesh INDIA" }, "email": "abhitest@gmail.com", "phone_number": "9878564524", "gender": "M", "dob": "1961-06-12", "input_dob": null, "aadhaar_linked": true, "dob_verified": false, "dob_check": false, "category": "person", "less_info": false }, "is_sole_proprietor": true, "is_director": true, "is_salaried": true }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

PAN Comprehensive V2

PAN Comprehensive V2#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

pan_details Object#

address Object#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

PAN Comprehensive V2

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

pan_details Object

address Object

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples