Prefill By Mobile

Endpoint Overview

POST /api/v1/prefill/prefill-by-mobile

Description

This API endpoint retrieves comprehensive customer data using a mobile number as the input parameter. It returns detailed personal information including identity details, contact information, address history, and more. The service helps businesses pre-populate forms, verify customer identity, and streamline onboarding processes by leveraging existing customer data.

Key Benefits

Reduces customer data entry time by auto-filling forms with verified information

Improves data accuracy by retrieving information from trusted sources

Enhances customer experience with faster onboarding processes

Provides comprehensive customer profile data from a single API call

Use Cases

Financial Services

Insurance

Telecom

Pre-populate loan application forms to reduce abandonment rates

Verify customer identity during account opening processes

Cross-check customer-provided information against existing records

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	String	Yes	Customer's mobile number

Example Request

{
    "mobile": "9660912345"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains all customer information
data.client_id	String	Unique identifier for the customer record
data.mobile	String	Customer's mobile number
data.details	Object	Customer's Details
data.details.personal_info	Object	Personal details including name, DOB, gender, etc.
data.details.phone_info	Array	List of phone numbers associated with the customer
data.details.address_info	Array	List of addresses associated with the customer
data.details.email_info	Array	List of email addresses associated with the customer
data.details.identity_info	Object	Various identity documents associated with the customer
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

Personal Info Object

Parameter	Type	Description
full_name	String	Full name of the person
dob	String	Date of birth in YYYY-MM-DD format
gender	String	Gender of the person (Male/Female)
total_income	String	Total income of the person
occupation	String	Occupation of the person
age	String	Age of the person

Phone Info Object

Parameter	Type	Description
reported_date	String	Date when the information was reported in YYYY-MM-DD format
type_code	String	Type code representing the nature of the data (e.g., M for Mobile, H for Home)
number	String	Phone number

Address Info Object

Parameter	Type	Description
address	String	Full address of the person
state	String	State where the address is located
type	String	Type of address (e.g., Permanent, Temporary, Office)
postal	String	Postal code or ZIP code
reported_date	String	Date when the information was reported in YYYY-MM-DD format

Email Info Object

Parameter	Type	Description
reported_date	String	Date when the information was reported in YYYY-MM-DD format
email_address	String	Email address associated with the reported date

Identity Info Object

Parameter	Type	Description
pan_number	Array	List of PAN card details
passport_number	Array	List of passport details
driving_license	Array	List of driving license details
voter_id	Array	List of voter ID details
aadhaar_number	Array	List of Aadhaar number details
ration_card	Array	List of ration card details
other_id	Array	List of other ID details

Example Successful Response

{
    "data": {
        "client_id": "prefill_by_mobile_FpyRXBhdoauvQNwrQzke",
        "mobile": "9660123456",
        "details": {
            "personal_info": {
                "full_name": "RAJENDRA SINGH ",
                "dob": "1968-10-20",
                "gender": "Male",
                "total_income": "",
                "occupation": "",
                "age": "55"
            },
            "phone_info": [
                {
                    "reported_date": "2024-01-28",
                    "type_code": "H",
                    "number": "00001427"
                },
                {
                    "reported_date": "2019-07-31",
                    "type_code": "M",
                    "number": "9660123456"
                },
                {
                    "reported_date": "2023-01-31",
                    "type_code": "M",
                    "number": "9660123456"
                }
            ],
            "address_info": [
                {
                    "address": "S/O SHIV PRASAD SINGH MAHWA",
                    "state": "RAJASTHAN",
                    "type": "Permanent",
                    "postal": "123456",
                    "reported_date": "2024-01-28"
                },
                {
                    "address": "UNIT-A-123456 RAM NAGARIA RAM NAGARIA  NEAR JAGATPURA JAIPUR JAIPUR JAIPUR",
                    "state": "RAJASTHAN",
                    "type": "",
                    "postal": "123456",
                    "reported_date": "2023-01-31"
                },
                {
                    "address": "TODABHIM DIST  KARAULI PATOLI TODABHIM",
                    "state": "RAJASTHAN",
                    "type": "Office",
                    "postal": "123456",
                    "reported_date": "2023-01-31"
                },
                {
                    "address": "WARD NO 4  DAUSA-123456",
                    "state": "RAJASTHAN",
                    "type": "Primary",
                    "postal": "123456",
                    "reported_date": "2023-01-31"
                },
                {
                    "address": "A 1001 RAM NAGARIYA",
                    "state": "RAJASTHAN",
                    "type": "Owns,Permanent",
                    "postal": "302017",
                    "reported_date": "2019-07-31"
                }
            ],
            "email_info": [
                {
                    "reported_date": "2021-06-30",
                    "email_address": "VISHALRATHORE@GMAIL.COM"
                }
            ],
            "identity_info": {
                "pan_number": [
                    {
                        "id_number": "CMGPA1234J"
                    }
                ],
                "passport_number": [],
                "driving_license": [],
                "voter_id": [
                    {
                        "id_number": "RJ100873123456"
                    }
                ],
                "aadhaar_number": [
                    {
                        "id_number": "XXXXXXXXXXXX"
                    }
                ],
                "ration_card": [],
                "other_id": []
            }
        }
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Mobile Number

No Data Found

Authentication Error

{
    "status_code": 400,
    "success": false,
    "message": "Invalid mobile number format",
    "message_code": "invalid_input"
}

The mobile number provided is not in a valid format or contains non-numeric characters.

Integration Best Practices

Security Recommendations

Store API credentials securely and never expose them in client-side code

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

Use HTTPS for all API communications to ensure data is encrypted in transit

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

Regularly rotate your JWT tokens and implement token expiration policies

User Experience Guidelines

Implement a fallback mechanism for manual data entry when the API doesn't return data

Display a loading indicator during API calls to inform users that data is being fetched

Allow users to review and edit pre-filled information before submission

Clearly communicate to users that their information is being retrieved from existing records

Implement proper validation on pre-filled data to ensure accuracy

Code Samples

cURL

Python

Node.js

Related APIs

Prefill By PAN: Fetches customer data using PAN card number as input

Prefill By Aadhaar: Retrieves customer information using Aadhaar number

Prefill By Name and DOB: Gets customer details using name and date of birth

Customer Verification: Verifies the authenticity of customer-provided information

Compliance and Legal Considerations

This API handles personally identifiable information (PII) and is subject to data protection regulations. Ensure you have proper consent from customers before retrieving their data. The use of this API must comply with relevant privacy laws including but not limited to GDPR, PDPA, and India's Personal Data Protection Bill. Implement appropriate data retention and deletion policies for any customer data retrieved through 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/prefill/prefill-by-mobile' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "mobile": "9660912345" }'

{ "data": { "client_id": "prefill_report_v2_FpyRXBhdoauvQNwrQzke", "name": "RAJENDRA SINGH", "mobile": "9660123456", "personal_info": { "full_name": "RAJENDRA SINGH ", "dob": "1968-10-20", "gender": "Male", "total_income": "", "occupation": "", "age": "55" }, "phone_info": [ { "reported_date": "2024-01-28", "type_code": "H", "number": "00001427" }, { "reported_date": "2019-07-31", "type_code": "M", "number": "9660123456" }, { "reported_date": "2023-01-31", "type_code": "M", "number": "9660123456" } ], "address_info": [ { "address": "S/O SHIV PRASAD SINGH MAHWA", "state": "RAJASTHAN", "type": "Permanent", "postal": "123456", "reported_date": "2024-01-28" }, { "address": "UNIT-A-123456 RAM NAGARIA RAM NAGARIA NEAR JAGATPURA JAIPUR JAIPUR JAIPUR", "state": "RAJASTHAN", "type": "", "postal": "123456", "reported_date": "2023-01-31" }, { "address": "TODABHIM DIST KARAULI PATOLI TODABHIM", "state": "RAJASTHAN", "type": "Office", "postal": "123456", "reported_date": "2023-01-31" }, { "address": "WARD NO 4 DAUSA-123456", "state": "RAJASTHAN", "type": "Primary", "postal": "123456", "reported_date": "2023-01-31" }, { "address": "A 1001 RAM NAGARIYA", "state": "RAJASTHAN", "type": "Owns,Permanent", "postal": "302017", "reported_date": "2019-07-31" } ], "email_info": [ { "reported_date": "2021-06-30", "email_address": "VISHALRATHORE@GMAIL.COM" } ], "identity_info": { "pan_number": [ { "id_number": "CMGPA1234J" } ], "passport_number": [], "driving_license": [], "voter_id": [ { "id_number": "RJ100873123456" } ], "aadhaar_number": [ { "id_number": "XXXXXXXXXXXX" } ], "ration_card": [], "other_id": [] } }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Prefill By Mobile

Prefill By Mobile#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Personal Info Object#

Phone Info Object#

Address Info Object#

Email Info Object#

Identity Info Object#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Prefill By Mobile

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Personal Info Object

Phone Info Object

Address Info Object

Email Info Object

Identity Info Object

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples