UDIN Send OTP API

Endpoint Overview

POST /api/v1/udin/send-otp

Description

The UDIN Send OTP API enables secure one-time password (OTP) delivery for UDIN (Unique Document Identification Number) verification processes. This endpoint initiates the verification workflow by sending an OTP to the user's registered mobile number, creating a secure client session for subsequent verification steps. The API is designed to support digital identity verification workflows that require multi-factor authentication through OTP validation.

This endpoint serves as the first step in a two-phase verification process, establishing a secure communication channel between your application and the end user while generating a unique client identifier for tracking the verification session.

Key Benefits

Enhanced Security: Multi-factor authentication through mobile OTP verification

Seamless Integration: Simple REST API with clear request/response structure

Session Management: Automatic client ID generation for tracking verification workflows

Real-time Delivery: Instant OTP delivery to registered mobile numbers

Use Cases

Financial Services

Healthcare

E-commerce

Account opening and KYC verification for banking customers

Loan application processing with identity verification

Digital wallet registration and user onboarding

Investment platform customer verification

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 JWT token for API authentication
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
name	String	Yes	Full name of the user as registered in official documents
id_number	String	Yes	UDIN (Unique Document Identification Number) for verification
email	String	Yes	Valid email address for communication and notifications
mobile_number	String	Yes	Mobile number where OTP will be sent (10-digit Indian mobile number)

Example Request

{
  "name": "Abhijit Shetye",
  "id_number": "21153743AAAADQ1234",
  "email": "abc@gmail.com",
  "mobile_number": "9876341246"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the core response data
data.client_id	String	Unique identifier for the verification session
data.otp_sent	Boolean	Indicates whether OTP was successfully sent
status_code	Integer	HTTP status code (200 for success)
success	Boolean	Overall success status of the request
message	String	Human-readable response message
message_code	String	Machine-readable response code

Example Successful Response

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

Possible Error Responses

Invalid Credentials

Invalid Input

{
  "data": null,
  "status_code": 401,
  "success": false,
  "message": "Invalid authentication token",
  "message_code": "unauthorized"
}

Authentication failure due to invalid or expired JWT token

Integration Best Practices

Security Recommendations

Store the client_id securely for subsequent verification steps

Implement proper JWT token management with appropriate expiration times

Validate all input parameters on the client side before sending requests

Use HTTPS only for all API communications

Implement rate limiting to prevent abuse of OTP generation

User Experience Guidelines

Inform users about expected OTP delivery time (typically 30-60 seconds)

Provide clear instructions about where to find the OTP (SMS)

Implement resend OTP functionality with appropriate cooldown periods

Display loading states during API calls to manage user expectations

Handle network errors gracefully with retry mechanisms

Code Samples

cURL

Python

Node.js

Related APIs

UDIN Verify OTP API: Verifies the OTP sent through this endpoint using the client_id

UDIN Status Check API: Retrieves the current status of a UDIN verification session

UDIN Document Verification API: Performs comprehensive document verification after OTP validation

Compliance and Legal Considerations

This API processes personal identifiable information (PII) including names, email addresses, and mobile numbers. Ensure compliance with applicable data protection regulations such as India's Personal Data Protection Bill and implement appropriate data handling, storage, and retention policies. The UDIN verification process should align with KYC and AML requirements as mandated by regulatory authorities in your jurisdiction.

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/udin/send-otp' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Abhijit Shetye", "id_number": "21153743AAAADQ1234", "email": "abc@gmail.com", "mobile_number": "9876341246" }'

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

UDIN Send OTP

UDIN Send OTP 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