PAN Masked Aadhaar

Endpoint Overview

POST /api/v1/pan/pan-masked-aadhaar

Description

The PAN Masked Aadhaar API enables you to retrieve the masked Aadhaar number associated with a given Permanent Account Number (PAN). This API establishes and verifies the linkage between PAN and Aadhaar while maintaining privacy by returning only the last 4 digits of the Aadhaar number.

This endpoint is essential for businesses that need to verify PAN-Aadhaar linkage for compliance purposes without exposing complete Aadhaar details. The API performs real-time validation against government databases to ensure accurate and up-to-date information while adhering to data privacy regulations.

Key Benefits

Privacy-Compliant Verification: Returns masked Aadhaar data, exposing only the last 4 digits to maintain user privacy

Real-Time Validation: Instant verification of PAN-Aadhaar linkage against authoritative government records

Regulatory Compliance: Helps meet KYC and identity verification requirements mandated by regulatory authorities

Seamless Integration: Simple REST API with straightforward request-response structure for easy implementation

Use Cases

Financial Services

Fintech & Digital Lending

Enterprise & HR

Account Opening: Verify PAN-Aadhaar linkage during customer onboarding for bank accounts, trading accounts, and insurance policies

Loan Processing: Validate identity documents as part of credit assessment and loan disbursement workflows

Compliance Verification: Ensure customers meet regulatory requirements for financial transactions and investments

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 YOUR_JWT_TOKEN`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
id_number	String	Yes	Valid 10-character PAN number in uppercase format (e.g., LJDPK1234L). Must follow PAN format: 5 letters, 4 digits, 1 letter

Example Request

{
    "id_number": "LJDPK1234L"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the verification results
data.client_id	String	Unique identifier for this verification request
data.pan_number	String	The PAN number that was verified
data.masked_aadhaar	String	Masked Aadhaar number with only last 4 digits visible (format: XXXXXXXX1234)
status_code	Integer	HTTP status code indicating the result of the request
success	Boolean	Indicates whether the request was successful (true) or failed (false)
message	String	Human-readable message describing the result
message_code	String	Machine-readable code for the result status

Example Successful Response

{
    "data": {
        "client_id": "pan_masked_aadhaar_lRMcdKoaVtmCjxequnrk",
        "pan_number": "LJDPK1234L",
        "masked_aadhaar": "XXXXXXXX1234"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid PAN

Unauthorized

Bad Request

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

This error occurs when the provided PAN number is invalid, incorrectly formatted, or not linked with any Aadhaar number in the government database.

Integration Best Practices

Security Recommendations

Token Security: Store JWT tokens securely using environment variables or secure credential management systems. Never expose tokens in client-side code or version control

HTTPS Only: Always use HTTPS endpoints to ensure encrypted data transmission between your application and the API

Token Rotation: Implement regular token refresh mechanisms and maintain separate tokens for sandbox and production environments

Rate Limiting: Implement appropriate retry logic with exponential backoff to handle rate limits gracefully

Data Retention: Store masked Aadhaar data only as long as necessary for compliance purposes and implement secure deletion policies

Access Control: Restrict API access to authorized services and implement proper authentication and authorization in your application

User Experience Guidelines

Input Validation: Validate PAN format on the client side before making API calls to reduce unnecessary requests and provide instant feedback

Clear Error Messages: Display user-friendly error messages when PAN validation fails, guiding users to correct their input

Loading States: Implement appropriate loading indicators during API calls to keep users informed of verification progress

Privacy Communication: Inform users that only masked Aadhaar information will be displayed to maintain transparency about data handling

Retry Mechanism: Allow users to retry verification in case of transient errors without requiring them to restart the entire process

Consent Management: Obtain explicit user consent before initiating PAN-Aadhaar verification as per regulatory requirements

Code Samples

cURL

Python

Node.js

Related APIs

PAN Verification API: Verify PAN details including name, date of birth, and card status
Aadhaar Verification API: Complete Aadhaar verification with demographic details and address information
PAN Comprehensive API: Retrieve detailed PAN information including holder name and status
Aadhaar eSign API: Enable digital signatures using Aadhaar-based authentication
DigiLocker Integration API: Access government-verified documents stored in DigiLocker using Aadhaar

Compliance and Legal Considerations

This API must be used in compliance with the Income Tax Act, Aadhaar Act, and associated data protection regulations. Organizations must:

Obtain explicit user consent before accessing PAN-Aadhaar linkage information

Use the data only for legitimate KYC and verification purposes as permitted by law

Implement appropriate security measures to protect masked Aadhaar data

Comply with data retention and deletion requirements as per applicable regulations

Ensure that masked Aadhaar information is not used to reconstruct complete Aadhaar numbers

Maintain audit trails of all verification requests for compliance reporting

Organizations are responsible for ensuring their use of this API complies with all applicable Indian laws, including the Information Technology Act, 2000, and associated rules. Consult legal counsel for specific compliance requirements in your industry.

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-masked-aadhaar' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "id_number": "LJDPK1234L" }'

{ "data": { "client_id": "pan_masked_aadhaar_lRMcdKoaVtmCjxequnrk", "pan_number": "LJDPK1234L", "masked_aadhaar": "XXXXXXXX1234" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses