Maharashtra Challan Initialization

Endpoint Overview

POST /api/v1/maharashtra-challan/init

Description

The Maharashtra Challan Initialization API enables businesses to retrieve linked mobile numbers associated with a vehicle registration in Maharashtra. This endpoint serves as the first step in the challan verification process, allowing you to identify all mobile numbers registered with the vehicle in the Maharashtra transport system. By providing the vehicle's RC (Registration Certificate) number and chassis number, you can retrieve a list of masked mobile numbers that can be used for subsequent OTP-based challan verification.

This API is essential for digital verification workflows, enabling secure and authorized access to vehicle challan information while maintaining user privacy through masked mobile number displays.

Key Benefits

Privacy-First Approach: Returns masked mobile numbers to protect user privacy while enabling verification

Multi-Number Support: Retrieves all mobile numbers linked to a vehicle, providing flexibility in verification

Seamless Integration: Simple request-response pattern that fits easily into existing workflows

Unique Client Identification: Generates a unique client_id for tracking subsequent verification requests

Use Cases

Financial Services

Fleet Management

E-commerce & Marketplaces

Vehicle loan verification workflows requiring challan checks before loan approval

Insurance policy issuance with automated challan verification for risk assessment

Vehicle refinancing processes with real-time outstanding challan validation

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	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
rc_number	string	Yes	Vehicle Registration Certificate number in Maharashtra format (e.g., MH01TE1234)
chassis_number	string	Optional	Vehicle chassis number as per registration documents (e.g., ME1KC111DH0123272)

Example Request

{
    "rc_number": "MH01TE1234"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object for response data
data.client_id	string	Unique identifier for this challan verification session (used in subsequent API calls)
data.rc_number	string	Echo of the requested RC number
data.chassis_number	string	Echo of the requested chassis number
data.linked_mobile_numbers	array	Array of mobile number objects linked to the vehicle
data.linked_mobile_numbers[].masked_mobile_number	string	Partially masked mobile number for privacy (format: XX*****XX)
data.linked_mobile_numbers[].mobile_number_id	string	Unique identifier for each mobile number (used for OTP verification)
status_code	integer	HTTP status code of the response
success	boolean	Indicates whether the request was successful
message	string	Human-readable response message
message_code	string	Machine-readable message code for programmatic handling

Example Successful Response

{
    "data": {
        "client_id": "maharashtra_challan_afqOprZOdrcDazuUndHP",
        "rc_number": "MH01TE1234",
        "chassis_number": "ME1KC111DH0123272",
        "linked_mobile_numbers": [
            {
                "masked_mobile_number": "63*****63",
                "mobile_number_id": "linked_mobile_BxgqkyuWmlysdkdsMtph"
            },
            {
                "masked_mobile_number": "77*****77",
                "mobile_number_id": "linked_mobile_uxyoBRNRvgNmxfTlZIgQ"
            },
            {
                "masked_mobile_number": "82*****82",
                "mobile_number_id": "linked_mobile_jrvXwTzlxcNKaYezGbtf"
            },
            {
                "masked_mobile_number": "97*****39",
                "mobile_number_id": "linked_mobile_RhQevbwcTapdWpfxhgkf"
            },
            {
                "masked_mobile_number": "97*****01",
                "mobile_number_id": "linked_mobile_QrNNaywJrXqLYzArjtqP"
            },
            {
                "masked_mobile_number": "98*****14",
                "mobile_number_id": "linked_mobile_BhIfxoGRNFtfWyyrAPOJ"
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Server Error

{
    "status_code": 500,
    "success": false,
    "message": "Internal server error",
    "message_code": "server_error"
}

This indicates a server-side issue. If this persists, contact Surepass support with the request details for investigation.

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.

HTTPS Only: Always use HTTPS endpoints for API calls to encrypt data in transit and prevent man-in-the-middle attacks.

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

Input Validation: Validate RC number and chassis number formats on the client side before making API calls to reduce unnecessary requests.

Rate Limiting: Implement appropriate rate limiting on your end to prevent abuse and manage API quota efficiently.

User Experience Guidelines

Display Masked Numbers Clearly: Present the masked mobile numbers in a user-friendly interface allowing users to identify their number by the visible digits.

Provide Context: Explain to users why mobile number selection is required and how it will be used for OTP verification.

Handle Multiple Numbers: Design your UI to accommodate multiple linked mobile numbers gracefully, allowing easy selection.

Error Communication: Display user-friendly error messages when vehicle details are not found, guiding users to verify their inputs.

Loading States: Implement loading indicators during API calls to provide feedback and improve perceived performance.

Code Samples

cURL

Python

Node.js

Related APIs

Maharashtra Challan OTP Request API - Use the client_id and mobile_number_id from this endpoint to request an OTP for challan verification.

Maharashtra Challan OTP Verify API - Verify the OTP and retrieve complete challan details for the vehicle.

Maharashtra Challan Status API - Check the current status of a challan verification request.

Compliance and Legal Considerations

This API accesses vehicle registration data maintained by the Maharashtra State Transport Department. Ensure compliance with the following:

Data Privacy: Use retrieved mobile numbers only for the intended verification purpose. Do not store or share mobile numbers without proper consent.

Purpose Limitation: Access vehicle challan information only for legitimate business purposes such as loan processing, insurance verification, or vehicle purchase due diligence.

Consent Management: Obtain explicit user consent before initiating challan verification on their behalf.

Data Retention: Follow appropriate data retention policies and delete verification data after the intended purpose is fulfilled.

Regulatory Compliance: Ensure compliance with IT Act 2000, Digital Personal Data Protection Act 2023, and Motor Vehicles Act 1988 requirements.

Authorized Use: This API should only be used by authorized entities with valid business use cases for vehicle verification.

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/maharashtra-challan/init' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "rc_number": "MH01TE1234" }'

{ "data": { "client_id": "maharashtra_challan_afqOprZOdrcDazuUndHP", "rc_number": "MH01TE1234", "chassis_number": "ME1KC111DH0123272", "linked_mobile_numbers": [ { "masked_mobile_number": "63*****63", "mobile_number_id": "linked_mobile_BxgqkyuWmlysdkdsMtph" }, { "masked_mobile_number": "77*****77", "mobile_number_id": "linked_mobile_uxyoBRNRvgNmxfTlZIgQ" }, { "masked_mobile_number": "82*****82", "mobile_number_id": "linked_mobile_jrvXwTzlxcNKaYezGbtf" }, { "masked_mobile_number": "97*****39", "mobile_number_id": "linked_mobile_RhQevbwcTapdWpfxhgkf" }, { "masked_mobile_number": "97*****01", "mobile_number_id": "linked_mobile_QrNNaywJrXqLYzArjtqP" }, { "masked_mobile_number": "98*****14", "mobile_number_id": "linked_mobile_BhIfxoGRNFtfWyyrAPOJ" } ] }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Init

Maharashtra Challan 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