Udyam OTP Async - Send OTP Status

Endpoint Overview

POST /api/v1/udyam-otp/async/send-otp-status

Description

The Udyam OTP Async - Send OTP Status API allows you to check the current delivery status of an OTP request that was previously initiated via the Udyam OTP Async Send OTP endpoint. Since OTP dispatch is handled asynchronously, this endpoint provides a reliable polling mechanism to determine whether the OTP has been successfully sent, is still being processed, or has failed for the registered mobile or email of the Udyam entity.

By submitting the client_id returned from the Send OTP call, your application can programmatically query the processing state and take appropriate action — such as prompting the user to enter the OTP once delivery is confirmed (otp_sent), waiting if the request is still in progress (pending), or triggering a resend flow if the dispatch failed (failed). This endpoint is particularly useful in scenarios where webhook-based callbacks are not configured or as a fallback to verify delivery status independently.

Key Benefits

Complete Status Visibility: Track the full lifecycle of an OTP dispatch — from pending through otp_sent or failed — giving your application precise control over the user verification flow.

Polling Fallback: Serves as a reliable alternative to webhook callbacks for environments where inbound webhook endpoints are not feasible or available.

Simple Integration: Requires only the client_id from the original Send OTP response, making it straightforward to layer onto existing verification workflows.

Failure Detection & Recovery: The failed status enables your application to detect delivery issues early and proactively trigger resend logic or alternate communication channels, improving overall completion rates.

Use Cases

Fintech & Lending

Government & Compliance

B2B Marketplaces

Poll OTP delivery status during MSME loan onboarding to confirm the applicant received the OTP before prompting them to enter it, reducing drop-offs caused by premature OTP input screens.

Detect failed status in automated underwriting pipelines and trigger a resend or escalation workflow to ensure the verification step is not silently skipped.

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 authentication. Format: `Bearer <JWT_TOKEN>`
`Content-Type`	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
`client_id`	String	Yes	The unique client identifier returned by the Udyam OTP Async Send OTP API. Used to look up the delivery status of a specific OTP dispatch request.

Example Request

{
    "client_id": "udyam_otp_async_bgKqddCbbfhmJGqouVIK"
}

Process Response

Response Parameters

Parameter	Type	Description
`data`	Object	Contains the status result for the OTP dispatch request
`data.client_id`	String	The unique client identifier corresponding to the original OTP request
`data.status`	String	The current delivery status of the OTP. Allowed values: `otp_sent` (OTP successfully dispatched), `pending` (OTP dispatch still in progress), `invalid_detail` (Invalid Mobile Number Or Udyam Number), `failed` (OTP dispatch was unsuccessful)
`status_code`	Integer	HTTP status code of the response (e.g., `200` for success)
`success`	Boolean	Indicates whether the API call was successful (`true`) or not (`false`)
`message`	String	A human-readable message describing the result (e.g., `"Success"`)
`message_code`	String	A machine-readable code corresponding to the message (e.g., `"success"`)

`data.status` Allowed Values

Status	Description	Recommended Action
`otp_sent`	The OTP has been successfully dispatched to the user's mobile or email	Prompt the user to enter the OTP to proceed with verification
`invalid_detail`	Invalid Mobile Number Or Udyam Number	Reinitiate the Flow With Correct Detail
`pending`	The OTP dispatch request is still being processed asynchronously	Continue polling after a short interval; do not prompt the user yet
`failed`	The OTP dispatch was unsuccessful	Surface an appropriate error to the user and offer a resend option

Example Successful Response

{
    "data": {
        "client_id": "udyam_otp_async_bgKqddCbbfhmJGqouVIK",
        "status": "otp_sent"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Unauthorized

Invalid Client ID

Internal Server Error

{
    "status_code": 401,
    "success": false,
    "message": "Authentication credentials were not provided or are invalid.",
    "message_code": "unauthorized"
}

Returned when the JWT Bearer token is missing, expired, or invalid. Ensure you are using the correct token for the target environment (sandbox or production).

Integration Best Practices

Security Recommendations

Protect the client_id: Treat the client_id as a session-scoped identifier. Avoid exposing it in client-side logs, browser URLs, or local storage to prevent unauthorized status lookups.

Use environment-specific tokens: Always use the JWT token issued for the corresponding environment — never use a production token against the sandbox base URL or vice versa.

Enforce server-side polling: Perform status polling from your backend rather than directly from the client to prevent token exposure and centralize rate limiting controls.

Set a polling timeout: Define a maximum number of polling attempts and an overall timeout duration to prevent indefinite polling loops when status remains pending for an extended period.

User Experience Guidelines

Poll with a reasonable interval: Wait at least 2–3 seconds between status poll requests to avoid overwhelming the API and to allow the async OTP dispatch process adequate time to complete.

Map statuses to UI states clearly: Show a "Sending OTP..." indicator for pending, enable the OTP input field only after otp_sent is confirmed, and display an actionable error message with a resend option when failed is received.

Limit polling attempts before surfacing an error: If the status remains pending after a defined number of attempts (e.g., 10 polls over 30 seconds), treat it as a soft failure and offer the user a resend option to avoid leaving them stuck indefinitely.

Provide a resend fallback for failed status: When failed is detected, prompt the user to retry the Send OTP request rather than asking them to re-enter the OTP, since no OTP was successfully delivered.

Code Samples

cURL

Python

Node.js

Related APIs

Udyam OTP Async - Send OTP: Initiates the asynchronous OTP dispatch to a Udyam-registered entity's mobile or email. Returns the client_id required by this status endpoint.

Udyam OTP Async - Verify OTP: Submits the OTP entered by the user along with the client_id to complete the Udyam registration verification process. Should only be called after this endpoint returns otp_sent.

Udyam Registration Verification: Directly verifies Udyam registration details without OTP for non-consent-based verification use cases.

Compliance and Legal Considerations

Data Minimization: This endpoint only requires the client_id and does not expose or transmit any personally identifiable information (PII) such as the mobile number or Udyam registration number. Ensure the client_id itself is stored and transmitted securely over HTTPS.

Audit Logging: Maintain server-side logs of status poll requests and their final responses — particularly the terminal otp_sent or failed states — as part of your KYC audit trail for regulatory review purposes.

Rate Limiting Compliance: Avoid aggressive polling intervals to stay within Surepass's acceptable use policies. Implement exponential backoff and a maximum retry cap to prevent runaway polling in production environments.

Regulatory Alignment: The use of this API as part of an MSME verification workflow should comply with India's Digital Personal Data Protection Act (DPDPA) and any applicable guidelines issued by the Ministry of MSME, Government of India.

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

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

Send OTP Status

Udyam OTP Async - Send OTP Status#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

data.status Allowed Values#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses