Mobile To Name

Endpoint Overview

POST /api/v1/mobile-to-name/verification

Description

The Mobile to Name API enables you to retrieve the full name associated with a given mobile number in India. This API performs a lookup against telecom operator databases to verify the identity of the mobile number owner, providing a reliable way to confirm user identities during onboarding or verification processes.

Key Benefits

Instant verification of mobile number ownership without requiring OTP

Reduces identity fraud by confirming the actual registered name

Streamlines user onboarding by pre-filling name fields automatically

Helps meet KYC compliance requirements with verified user information

Use Cases

Financial Services

E-commerce

Telecom

Pre-fill customer information during account opening

Verify customer identity during loan applications

Confirm mobile number ownership for payment registrations

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 authentication using JWT token
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
mobile_number	String	Yes	The mobile number to verify (10 digits without country code)

Example Request

{
    "mobile_number": "8079012345"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the verification result data
data.client_id	String	Unique identifier for this verification request
data.name	String	Full name associated with the mobile number
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Human-readable status message
message_code	String	Machine-readable status code

Example Successful Response

{
    "data": {
        "client_id": "mobile_to_name_DtQgHfeoGjtpUYmisKvt",
        "name": "VISHAL SINGH RATHORE"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Mobile Number

Number Not Found

Authentication Error

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

The mobile number provided is not in the correct format. Ensure it's a 10-digit number without country code.

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

Rotate JWT tokens periodically to minimize risk from token compromise

User Experience Guidelines

Inform users that their mobile number will be used for name verification

Implement proper validation for mobile number input (10 digits, numeric only)

Display a loading indicator during the API call to improve perceived performance

Provide clear error messages when verification fails for any reason

Code Samples

cURL

Python

Node.js

Related APIs

PAN Verification API: Verify PAN card details and retrieve associated information

Aadhaar Verification API: Verify Aadhaar card details with OTP authentication

Bank Account Verification API: Verify bank account details and ownership

Address Verification API: Verify and validate user addresses

Compliance and Legal Considerations

This API should be used in compliance with telecom regulations and data privacy laws in India. Ensure you have proper consent from users before verifying their mobile numbers. The data retrieved should be handled according to applicable data protection regulations, including proper storage, usage limitations, and retention policies.

{ "data": { "client_id": "mobile_to_name_DtQgHfeoGjtpUYmisKvt", "name": "VISHAL SINGH RATHORE" }, "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 ********************

Mobile To Name

Mobile To Name#

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

Mobile To Name

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples