Mobile To Prefill V2

Endpoint Overview

POST /api/v1/pan/mobile-to-prefill-v2

Description

This API endpoint retrieves comprehensive PAN card details associated with a provided mobile number. It enables seamless pre-filling of user information in your application by fetching verified PAN data, eliminating manual data entry and reducing errors. The service returns complete PAN details including personal information, address, and verification status, allowing you to streamline your KYC processes.

Key Benefits

Eliminates manual data entry by auto-populating user information from verified PAN records

Reduces errors and improves data accuracy through official source verification

Streamlines user onboarding by minimizing form fields that need to be filled manually

Enhances KYC compliance by retrieving verified identity information

Use Cases

Financial Services

Insurance

Digital Services

Pre-filling customer information during account opening processes

Streamlining loan application forms with verified PAN details

Automating KYC verification for investment 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
mobile_number	String	Yes	The mobile number associated with the PAN card details you want to retrieve

Example Request

{
    "mobile_number": "8079012345"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the retrieved PAN card details
data.client_id	String	Unique identifier for the client request
data.mobile_number	String	Mobile number provided in the request
data.pan_number	String	PAN number associated with the mobile number
data.pan_details	Object	Comprehensive PAN card details
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Response message
message_code	String	Code representing the response message

pan_details Object

Parameter	Type	Description
pan_number	String	PAN number of the individual
full_name	String	Full name as per PAN card
full_name_split	List	Full name split into first name, middle name (if any), and last name
masked_aadhaar	String	Masked Aadhaar number
address	Object	Object containing address details
email	String	Email address associated with the PAN card
phone_number	String	Phone number associated with the PAN card
gender	String	Gender of the individual (M/F/Others)
dob	String	Date of birth in YYYY-MM-DD format
input_dob	String	Input date of birth if provided
aadhaar_linked	Boolean	Indicates if Aadhaar is linked with the PAN card
dob_verified	Boolean	Indicates if the date of birth is verified
dob_check	Boolean	Indicates if there was a check on the date of birth
category	String	Category of the individual (e.g., person, company)
less_info	Boolean	Indicates if less information is available

address Object

Parameter	Type	Description
line_1	String	Address line 1
line_2	String	Address line 2
street_name	String	Name of the street
zip	String	Zip code
city	String	City name
state	String	State name
country	String	Country name
full	String	Full address with all details concatenated

Example Successful Response

{
    "data": {
        "client_id": "mobile_to_prefill_v2_IGVFgraWemsveptOUkhp",
        "mobile_number": "8079012345",
        "pan_number": "ABCDE1234F",
        "pan_details": {
            "pan_number": "ABCDE1234F",
            "full_name": "John Doe",
            "masked_aadhaar": "XXXXXXXXXXXX",
            "address": {
                "line_1": "123, ABC Street",
                "line_2": "XYZ Area",
                "street_name": "ABC Street",
                "zip": "12345",
                "city": "Cityville",
                "state": "Stateville",
                "country": "Countryland",
                "full": "123, ABC Street XYZ Area Cityville, Stateville - 12345 Countryland"
            },
            "email": "johndoe@example.com",
            "phone_number": "8079012345",
            "gender": "M",
            "dob": "1990-01-01",
            "aadhaar_linked": true,
            "dob_verified": true,
            "dob_check": true,
            "category": "person",
            "less_info": false
        }
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Mobile Number

Authentication Error

{
    "status_code": 422,
    "success": false,
    "message": "Verification Failed.",
    "message_code": "verification_failed"
}

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

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement proper error handling to avoid exposing sensitive information

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

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

User Experience Guidelines

Inform users that their PAN details will be fetched using their mobile number

Provide clear feedback during the verification process with appropriate loading states

Allow users to review and confirm the fetched information before final submission

Implement fallback options for manual entry if the API fails to retrieve information

Code Samples

cURL

Python

Node.js

Related APIs

PAN Verification API: Verifies PAN card details against government records

PAN OCR API: Extracts information from PAN card images

Aadhaar Verification API: Verifies Aadhaar card details for enhanced KYC

Compliance and Legal Considerations

This API handles personal identifiable information (PII) and is subject to data protection regulations. Ensure you have proper user consent before retrieving their PAN details. The data should be stored securely and used only for the purpose disclosed to the user. Compliance with local KYC and data protection laws, including but not limited to GDPR (if applicable) and India's Personal Data Protection Bill, is essential when using this API.

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/mobile-to-prefill-v2' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "mobile_number": "8079012345" }'

{ "data": { "client_id": "mobile_to_prefill_v2_IGVFgraWemsveptOUkhp", "mobile_number": "8079012345", "pan_number": "ABCDE1234F", "pan_details": { "pan_number": "ABCDE1234F", "full_name": "John Doe", "masked_aadhaar": "XXXXXXXXXXXX", "address": { "line_1": "123, ABC Street", "line_2": "XYZ Area", "street_name": "ABC Street", "zip": "12345", "city": "Cityville", "state": "Stateville", "country": "Countryland", "full": "123, ABC Street XYZ Area Cityville, Stateville - 12345 Countryland" }, "email": "johndoe@example.com", "phone_number": "8079012345", "gender": "M", "dob": "1990-01-01", "aadhaar_linked": true, "dob_verified": true, "dob_check": true, "category": "person", "less_info": false } }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Mobile To Prefill V2

Mobile To Prefill 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

Mobile To Prefill 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