Mobile RC IDV Underwriting Initialization

Endpoint Overview

POST /api/v1/underwriting/mobile-rc-idv-underwriting/init

Description

The Mobile RC IDV Underwriting Initialization API initiates the identity verification and underwriting process for vehicle registration certificate (RC) verification linked to a mobile number. This endpoint creates a new underwriting session, validates the provided mobile number, and returns a unique client identifier for tracking the verification process throughout its lifecycle.

This API serves as the entry point for mobile-based vehicle ownership verification workflows, enabling businesses to verify that a mobile number is associated with a registered vehicle and initiate comprehensive underwriting checks. The endpoint returns immediately with a session status while the actual verification process may continue asynchronously.

Key Benefits

Streamlined Onboarding: Initiate vehicle ownership verification with just a mobile number, reducing friction in customer onboarding

Fraud Prevention: Establish a verified link between mobile numbers and vehicle ownership before extending services

Async Processing: Get immediate session creation with pending status, allowing for non-blocking integration patterns

Session Tracking: Receive a unique client_id for monitoring verification progress and retrieving results

Use Cases

Insurance

Financial Services

Mobility & Logistics

Motor Insurance Underwriting: Verify vehicle ownership before issuing insurance policies or calculating premiums

Claims Processing: Validate that the claimant's mobile number matches registered vehicle ownership records

Policy Renewal: Cross-verify customer details during renewal processes to prevent fraud

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.app

Production: https://kyc-api.surepass.app

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	JWT Bearer token for authentication (Format: `Bearer <token>`)
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
mobile_number	string	Yes	10-digit mobile number associated with the vehicle registration. Must be a valid Indian mobile number without country code or special characters.

Example Request

{
    "mobile_number": "9876543210"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object holding the response data
data.client_id	string	Unique identifier for tracking this underwriting session. Use this ID to check status or retrieve results.
data.mobile_number	string	The mobile number submitted in the request, returned for confirmation
data.status	string	Current status of the underwriting process. Initial value is typically "pending" indicating the verification is in progress.
status_code	number	HTTP status code indicating the result of the API call (200 for success)
success	boolean	Indicates whether the API request was successful (true) or failed (false)
message	string	Human-readable message describing the result of the operation
message_code	string	Machine-readable code for programmatic handling of the response

Example Successful Response

{
    "data": {
        "client_id": "mobile_rc_idv_underwriting_noPtef",
        "mobile_number": "9876543210",
        "status": "pending"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Unauthorized

Server Error

{
    "data": null,
    "status_code": 401,
    "success": false,
    "message": "Unauthorized access",
    "message_code": "unauthorized"
}

Returned when the JWT token is missing, invalid, or expired

Integration Best Practices

Security Recommendations

Secure Token Storage: Never expose JWT tokens in client-side code or version control systems. Store tokens securely in environment variables or secure vaults.

Token Rotation: Implement regular token refresh mechanisms to minimize security risks from token compromise.

HTTPS Only: Always use HTTPS endpoints in production to ensure data encryption in transit.

Input Validation: Validate mobile numbers on the client side before API calls to reduce unnecessary requests and potential abuse.

Rate Limiting: Implement client-side rate limiting and exponential backoff to handle API limits gracefully.

Log Sanitization: Ensure mobile numbers and sensitive response data are properly masked in application logs.

User Experience Guidelines

Immediate Feedback: Display a loading indicator immediately after initiating the verification to inform users the process has started.

Status Polling: Implement periodic polling using the returned client_id to check verification status and update users on progress.

Error Handling: Provide clear, user-friendly error messages when verification fails, avoiding technical jargon.

Timeout Management: Set appropriate timeout values (recommended 30-60 seconds) and inform users if verification is taking longer than expected.

Mobile Number Formatting: Accept mobile numbers in various formats (with/without spaces, dashes) but normalize them before sending to the API.

Retry Mechanism: Allow users to retry verification if it fails, with a reasonable cooldown period to prevent abuse.

Code Samples

cURL

Python

Node.js

Related APIs

Mobile RC IDV Underwriting Status: Check the current status of an initiated underwriting session using the client_id

RC Verification API: Direct vehicle registration certificate verification without underwriting workflow

Mobile Number Verification API: Standalone mobile number validation and carrier information lookup

Compliance and Legal Considerations

Data Privacy: This API processes personal information (mobile numbers) and vehicle registration data. Ensure compliance with applicable data protection regulations including the Information Technology Act, 2000 and Digital Personal Data Protection Act, 2023 (India). Obtain explicit user consent before initiating verification and clearly communicate how the data will be used.

Purpose Limitation: Use verification data only for the stated purpose (underwriting, identity verification, fraud prevention). Do not repurpose data for marketing or other unrelated activities without additional consent.

Data Retention: Implement appropriate data retention policies and securely delete verification data when no longer needed for the business purpose.

Regulatory Compliance: Motor vehicle verification may be subject to regulations by the Ministry of Road Transport and Highways (MoRTH) and insurance regulators. Ensure your use case complies with applicable sector-specific regulations.

User Rights: Provide mechanisms for users to access, correct, or request deletion of their verification data in accordance with data protection laws.

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/underwriting/mobile-rc-idv-underwriting/init' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "mobile_number": "9876543210" }'

{ "data": { "client_id": "mobile_rc_idv_underwriting_noPtef", "mobile_number": "9876543210", "status": "pending" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Init

Mobile RC IDV Underwriting Initialization#

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