Generate OTP

Endpoint Overview

POST /api/v1/pmfby/policy/generate-otp

Description

The Generate OTP API enables secure verification of mobile numbers for Pradhan Mantri Fasal Bima Yojana (PMFBY) policy holders. This endpoint initiates the authentication process by sending a one-time password (OTP) to the registered mobile number, ensuring secure access to policy information and services.

This API is designed to provide a seamless and secure authentication mechanism for farmers and agricultural stakeholders who need to verify their identity before accessing PMFBY policy details, making claims, or updating policy information.

Key Benefits

Enhanced Security: Implements two-factor authentication using mobile OTP verification

Quick Integration: Simple request structure with minimal required parameters

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

Comprehensive Response: Returns client ID for tracking the verification session

Use Cases

Agriculture & Insurance

Financial Services

Digital Platforms

Farmers verifying their identity to check PMFBY policy status and coverage details

Insurance agents authenticating policy holders before processing crop insurance claims

Agricultural cooperatives enabling secure access to member policy information

Government portals facilitating farmer authentication for subsidy 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	JWT Bearer token for API 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 registered with the PMFBY policy. Must be a valid Indian mobile number without country code or special characters

Example Request

{
    "mobile_number": "9900000000"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Contains the OTP generation response details
data.client_id	string	Unique identifier for the OTP session, used for subsequent verification steps
data.mobile_number	string	The mobile number to which OTP was sent
data.otp_generated	boolean	Indicates whether OTP was successfully generated and sent (true/false)
status_code	integer	HTTP status code of the response
success	boolean	Indicates if the API request was successful
message	string	Human-readable message describing the result
message_code	string	Machine-readable code for the response status

Example Successful Response

{
    "data": {
        "client_id": "pmfby_policy_blYspig",
        "mobile_number": "9900000000",
        "otp_generated": true
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Mobile Number

Unauthorized Access

Rate Limit Exceeded

Server Error

{
    "data": null,
    "status_code": 400,
    "success": false,
    "message": "Invalid mobile number format",
    "message_code": "invalid_mobile"
}

This error occurs when the mobile number format is incorrect or does not meet validation requirements (e.g., not 10 digits, contains special characters).

Integration Best Practices

Security Recommendations

Store JWT tokens securely using environment variables or secure credential management systems

Implement token refresh mechanism to avoid authentication failures due to token expiration

Never expose API credentials or tokens in client-side code or version control systems

Use HTTPS for all API communications to prevent man-in-the-middle attacks

Implement rate limiting on your application layer to prevent abuse

Store the client_id securely for subsequent OTP verification requests

Validate mobile number format on the client side before making API calls

User Experience Guidelines

Display clear messaging to users about OTP delivery (usually 30-60 seconds)

Provide a resend OTP option with appropriate cooldown period (typically 30-60 seconds)

Show masked mobile number to users for confirmation before sending OTP

Implement timeout handling with user-friendly error messages

Allow users to edit mobile number if OTP is not received

Display retry attempts remaining to prevent account lockout confusion

Provide alternative contact methods for support if OTP delivery fails

Code Samples

cURL

Python

Node.js

Compliance and Legal Considerations

This API processes personal information (mobile numbers) and must comply with India's Digital Personal Data Protection Act, 2023

Ensure proper consent is obtained from policy holders before collecting and processing their mobile numbers

OTPs should have appropriate expiration times (typically 5-10 minutes) for security purposes

Implement logging and audit trails for OTP generation requests for compliance and fraud prevention

Follow IRDAI (Insurance Regulatory and Development Authority of India) guidelines for digital authentication in insurance services

Maintain data residency requirements as per Indian data protection regulations

Implement appropriate data retention policies and securely delete OTP-related data after 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/pmfby/policy/generate-otp' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "mobile_number": "9900000000" }'

{ "data": { "client_id": "pmfby_policy_blYspigeEF", "mobile_number": "9900000000", "otp_generated": true }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

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