Mobile RC IDV Underwriting Status API

Endpoint Overview

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

Description

The Mobile RC IDV Underwriting Status API is a comprehensive verification endpoint that performs multi-layered identity verification by linking a mobile number to a person's name, retrieving associated vehicle registration (RC) numbers, and calculating the Insured Declared Value (IDV) of the registered vehicles. This API provides a complete underwriting workflow status for mobile-based vehicle insurance verification.

This endpoint orchestrates three sequential verification processes:

Mobile-to-Name Verification: Validates and retrieves the full name associated with the provided mobile number

Mobile-to-RC Linking: Identifies all vehicle registration certificates (RC) linked to the mobile number

RC-to-IDV Calculation: Computes the Insured Declared Value for the identified vehicles

The API is designed for asynchronous processing, allowing clients to check the status of previously initiated verification requests. It returns comprehensive results including verification status, user details, vehicle information, and calculated IDV values.

Key Benefits

Multi-Stage Verification: Combines identity, mobile, and vehicle verification in a single unified workflow

Comprehensive Data Retrieval: Returns full name, RC numbers, and IDV calculations in one response

Asynchronous Status Tracking: Poll-based architecture allows monitoring of long-running verification processes

Financial Risk Assessment: Provides calculated IDV values essential for underwriting decisions and premium calculations

Use Cases

Insurance & Financial Services

Lending & NBFC

Automobile & Mobility

Vehicle Insurance Underwriting: Verify customer identity and vehicle ownership before issuing insurance policies

Premium Calculation: Use IDV values to accurately calculate insurance premiums based on vehicle valuation

Fraud Detection: Cross-verify mobile numbers with registered vehicle owners to prevent insurance fraud

Risk Assessment: Evaluate underwriting risk by analyzing the relationship between identity, mobile, and vehicle ownership

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 for the target environment.

Include in Requests: Add the token to the Authorization header as Bearer {TOKEN}.

Different authentication tokens are used for sandbox and production environments:

Sandbox Environment: https://sandbox.surepass.app

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

Important: Ensure you use the correct JWT token corresponding to your target environment. Tokens are environment-specific and cannot be used interchangeably.

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	JWT Bearer token for API authentication. Format: `Bearer {your_jwt_token}`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
client_id	string	Yes	Unique identifier for the underwriting verification request. This ID is used to track and retrieve the status of the verification process across multiple API calls.

Example Request

{
    "client_id": "mobile_rc_idv_underwriting_noPtef"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object holding all verification results and status information
data.client_id	string	Echo of the request client_id used to track this verification
data.mobile_number	string	Mobile number associated with the verification request (10-digit format)
data.result	string	Calculated Insured Declared Value (IDV) for the registered vehicles in rupees
data.mobile_to_name_status	string	Status of mobile-to-name verification process. Values: `pending`, `in_progress`, `completed`, `failed`
data.full_name	string	Full name of the person associated with the mobile number (uppercase format)
data.mobile_to_rc_status	string	Status of mobile-to-RC linking process. Values: `pending`, `in_progress`, `completed`, `failed`
data.rc_numbers	array[string]	Array of vehicle registration certificate numbers linked to the mobile number
data.rc_to_idv_status	string	Status of RC-to-IDV calculation process. Values: `pending`, `in_progress`, `completed`, `failed`
data.status	string	Overall status of the entire verification workflow. Values: `pending`, `in_progress`, `completed`, `failed`
status_code	integer	HTTP status code of the response (200 for success)
success	boolean	Indicates whether the API request was successful
message	string	Human-readable message describing the result
message_code	string	Machine-readable code for programmatic response handling

Example Successful Response

{
    "data": {
        "client_id": "mobile_rc_idv_underwriting_noPtef",
        "mobile_number": "9876543210",
        "result": "243021.0",
        "mobile_to_name_status": "completed",
        "full_name": "RAJIV TALWAR",
        "mobile_to_rc_status": "completed",
        "rc_numbers": [
            "AB12CD3456"
        ],
        "rc_to_idv_status": "completed",
        "status": "completed"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Client ID

Authentication Failed

Verification In Progress

Verification Failed

{
    "data": null,
    "status_code": 404,
    "success": false,
    "message": "Client ID not found",
    "message_code": "client_id_not_found"
}

This error occurs when the provided client_id does not exist in the system or has not been initiated through the underwriting workflow.

Integration Best Practices

Security Recommendations

Secure Token Storage: Store JWT tokens securely using environment variables or secure vault services, never hardcode them in source code

Token Rotation: Implement token refresh mechanisms and rotate tokens regularly to minimize security risks

HTTPS Only: Always use HTTPS for API calls to ensure data encryption in transit

Rate Limiting: Implement client-side rate limiting to avoid overwhelming the API and ensure fair usage

Error Handling: Never expose raw API error messages to end users; log detailed errors securely and show user-friendly messages

Data Privacy: Handle personal information (names, mobile numbers, RC numbers) in compliance with local data protection regulations

Audit Logging: Maintain detailed logs of all API requests and responses for compliance and troubleshooting purposes

User Experience Guidelines

Polling Strategy: Implement exponential backoff when polling for status updates (e.g., 2s, 4s, 8s intervals) to balance responsiveness with API efficiency

Progress Indicators: Display real-time progress to users based on individual verification stage statuses (mobile_to_name_status, mobile_to_rc_status, rc_to_idv_status)

Timeout Handling: Set reasonable timeout limits (recommended 2-3 minutes) and inform users if verification exceeds expected duration

Clear Status Communication: Translate technical status codes into user-friendly messages (e.g., "Verifying your details..." instead of "in_progress")

Partial Results: Display completed verification stages even when the overall process is still in progress

Error Recovery: Provide clear next steps when verification fails, such as verifying mobile number accuracy or contacting support

Data Transparency: Inform users about what data is being verified and why, especially when handling sensitive information

Code Samples

cURL

Python

Node.js

Related APIs

Mobile RC IDV Underwriting Initiation API: Initiates the verification workflow and returns a client_id for status tracking

Mobile Number Verification API: Standalone API for verifying mobile numbers and retrieving associated names

RC Verification API: Verifies vehicle registration certificates and retrieves owner details

IDV Calculation API: Calculates Insured Declared Value for vehicles based on registration details

Comprehensive Underwriting Report API: Generates detailed underwriting reports including all verification stages

Compliance and Legal Considerations

Data Privacy: This API processes personal information including mobile numbers, names, and vehicle registration details. Ensure compliance with applicable data protection laws such as GDPR, India's Digital Personal Data Protection Act (DPDPA), and other regional privacy regulations.

Consent Management: Obtain explicit user consent before initiating verification processes. Maintain records of consent for audit purposes.

Data Retention: Implement appropriate data retention and deletion policies in accordance with legal requirements and business needs.

Purpose Limitation: Use the retrieved data only for the stated purpose (underwriting, verification) and not for unrelated marketing or profiling activities.

Third-Party Sharing: If sharing verification results with third parties, ensure proper data processing agreements are in place.

Right to Access: Be prepared to provide users access to their verification data and allow corrections if inaccuracies are found.

Regulatory Compliance: Vehicle insurance underwriting may be subject to regulations from insurance regulatory authorities (e.g., IRDAI in India). Ensure your use of this API complies with all applicable insurance and financial services regulations.

Audit Trail: Maintain comprehensive logs of all verification requests for regulatory audits and dispute resolution.

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/status' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "mobile_rc_idv_underwriting_noPtef" }'

{ "data": { "client_id": "mobile_rc_idv_underwriting_noPtef", "mobile_number": "9876543210", "result": "243021.0", "mobile_to_name_status": "completed", "full_name": "RAJIV TALWAR", "mobile_to_rc_status": "completed", "rc_numbers": [ "AB12CD3456" ], "rc_to_idv_status": "completed", "status": "completed" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Status

Mobile RC IDV Underwriting Status API#

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