Prefill Report

Endpoint Overview

POST /api/v1/prefill/prefill-report-v2

Description

The Prefill Report API retrieves comprehensive customer information using only their name and mobile number as input. This endpoint provides a detailed profile including personal information, contact details, address history, email information, and various identity documents associated with the customer. It enables businesses to pre-populate forms, verify customer identity, and streamline onboarding processes with minimal customer input.

Key Benefits

Reduce customer data entry by auto-filling forms with verified information

Access comprehensive customer profile data from a single API call

Improve KYC processes with historical address and identity document verification

Enhance customer experience by minimizing form-filling friction

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 verified data sources

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

Example Request

{
    "name": "Rajendra Singh",
    "mobile": "9660123456"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains all customer information
data.client_id	String	Unique identifier for the prefill report request
data.name	String	Customer's full name (as retrieved from records)
data.mobile	String	Customer's mobile number
data.personal_info	Object	Personal details including name, DOB, gender, income, occupation, and age
data.phone_info	Array	List of phone numbers associated with the customer
data.address_info	Array	List of addresses associated with the customer
data.email_info	Array	List of email addresses associated with the customer
data.identity_info	Object	Various identity documents associated with the customer
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

Example Successful Response

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

Possible Error Responses

Authentication Error

Customer Not Found

Invalid Input

{
    "status_code": 401,
    "success": false,
    "message": "Invalid or expired token",
    "message_code": "unauthorized"
}

This error occurs when the JWT token is missing, invalid, or expired.

Response Object Details

personal_info Object

Field	Type	Description
full_name	String	Customer's complete name
dob	String	Date of birth in YYYY-MM-DD format
gender	String	Gender (Male/Female)
total_income	String	Annual income (if available)
occupation	String	Professional occupation (if available)
age	String	Current age in years

phone_info Array Objects

Field	Type	Description
reported_date	String	Date when the phone number was reported in YYYY-MM-DD format
type_code	String	Type of phone number (M: Mobile, H: Home, etc.)
number	String	The phone number

address_info Array Objects

Field	Type	Description
address	String	Complete address details
state	String	State of the address
type	String	Address type (Permanent, Office, Primary, etc.)
postal	String	Postal/ZIP code
reported_date	String	Date when the address was reported in YYYY-MM-DD format

email_info Array Objects

Field	Type	Description
reported_date	String	Date when the email was reported in YYYY-MM-DD format
email_address	String	Email address

identity_info Object

Field	Type	Description
pan_number	Array	PAN card details
passport_number	Array	Passport details (if available)
driving_license	Array	Driving license details (if available)
voter_id	Array	Voter ID details (if available)
aadhaar_number	Array	Aadhaar number details (if available)
ration_card	Array	Ration card details (if available)
other_id	Array	Other identification documents (if available)

Integration Best Practices

Security Recommendations

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

Implement token rotation and expiration policies

Validate and sanitize all user inputs before passing to the API

Implement proper error handling to avoid exposing sensitive information

Use HTTPS for all API communications

User Experience Guidelines

Inform users that their information is being retrieved from external sources

Provide users the opportunity to review and correct pre-filled information

Implement progressive loading indicators during API calls

Allow users to manually enter information if the API doesn't return expected data

Clearly communicate which fields were auto-filled versus requiring manual input

Code Samples

cURL

Python

Node.js

Related APIs

Prefill Report V1: Previous version of the prefill report API with limited data fields

Prefill Report Verification: Verifies the accuracy of prefilled data against provided information

Customer Search: Searches for customers using multiple parameters beyond name and mobile

Document Verification: Verifies identity documents against official databases

Compliance and Legal Considerations

This API accesses personal information and is subject to data privacy regulations. Ensure you have proper consent from customers before retrieving their data. Usage of this API must comply with applicable data protection laws including but not limited to GDPR, CCPA, and India's Personal Data Protection Bill. Implement appropriate data retention and deletion policies for information retrieved through this API.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/prefill/prefill-report-v2' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Rajendra Singh", "mobile": "9660123456" }'

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

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Prefill Report

Prefill Report#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Response Object Details#

personal_info Object#

phone_info Array Objects#

address_info Array Objects#

email_info Array Objects#

identity_info Object#

Integration Best Practices#

Code Samples#

Request

Responses

Prefill Report

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Response Object Details

personal_info Object

phone_info Array Objects

address_info Array Objects

email_info Array Objects

identity_info Object

Integration Best Practices

Code Samples