Submit OTP

Endpoint Overview

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

Description

The PMFBY Policy OTP Submission API enables verification of One-Time Passwords (OTP) for Pradhan Mantri Fasal Bima Yojana (PMFBY) policy applications. This endpoint is a critical component of the secure policy enrollment process, validating OTPs sent to farmers or policy applicants to confirm their identity and complete the verification workflow.

This API plays a vital role in the agricultural insurance ecosystem by ensuring that only authorized individuals can proceed with policy submissions. By implementing OTP-based verification, it adds an essential security layer to protect both the insurance provider and the policy applicant from fraudulent activities.

Key Benefits

Enhanced Security: Implements two-factor authentication through OTP verification, preventing unauthorized policy submissions

Fraud Prevention: Validates user identity before finalizing policy applications, reducing fraudulent claims

Streamlined Verification: Provides instant OTP validation feedback, enabling real-time policy processing

Compliance Ready: Supports regulatory requirements for identity verification in government-sponsored insurance schemes

Use Cases

Agriculture & Insurance

Fintech & Banking

Government & AgriTech

Farmer Policy Enrollment: Verify farmers' identity during PMFBY crop insurance application process

Bulk Policy Processing: Enable insurance agents to validate multiple policy applications with OTP confirmation

Digital KYC Completion: Complete the digital know-your-customer process for agricultural insurance schemes

Policy Modification: Authenticate policy holders when making changes to existing coverage

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
client_id	string	Yes	Unique identifier for the PMFBY policy application session (generated during initial policy request)
otp	string	Yes	6-digit One-Time Password sent to the applicant's registered mobile number for verification

Example Request

{
    "client_id": "pmfby_policy_blYspig",
    "otp": "123456"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Contains the verification result details
data.client_id	string	Echo of the submitted client_id for reference tracking
data.otp_submitted	boolean	Indicates whether OTP submission was successful (true/false)
status_code	integer	HTTP status code of the response (200 for success)
success	boolean	Overall success indicator of the API call
message	string	Human-readable message describing the result
message_code	string	Machine-readable code for programmatic handling

Example Successful Response

{
    "data": {
        "client_id": "pmfby_policy_blYspig",
        "otp_submitted": true
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid OTP

Invalid Client ID

Authentication Error

Rate Limit Exceeded

{
    "data": null,
    "status_code": 422,
    "success": false,
    "message": "Invalid OTP provided",
    "message_code": "invalid_otp"
}

Occurs when the submitted OTP does not match the one sent to the user or has expired (typically valid for 5-10 minutes).

Integration Best Practices

Security Recommendations

Secure Token Storage: Never expose JWT tokens in client-side code or version control systems; store them securely in environment variables

HTTPS Only: Always use HTTPS endpoints to prevent man-in-the-middle attacks and ensure encrypted data transmission

OTP Attempt Limiting: Implement client-side rate limiting to prevent brute-force attacks on OTP verification

Session Timeout Handling: Monitor client_id expiration and implement proper session management to avoid stale verification attempts

Input Validation: Sanitize and validate both client_id and OTP inputs before sending to prevent injection attacks

Error Message Handling: Avoid exposing sensitive system information in error messages shown to end users

User Experience Guidelines

Clear Instructions: Display clear messaging about OTP validity period (typically 5-10 minutes) and format (6 digits)

Resend Option: Provide a "Resend OTP" option if the user doesn't receive it, with appropriate cooldown periods

Attempt Counter: Show remaining verification attempts to users to prevent lockouts and reduce frustration

Loading States: Display appropriate loading indicators during API calls to improve perceived performance

Error Recovery: Provide actionable error messages and clear next steps when OTP verification fails

Accessibility: Ensure OTP input fields are accessible with proper ARIA labels and support for assistive technologies

Code Samples

cURL

Python

Node.js

Compliance and Legal Considerations

This API processes data related to the Pradhan Mantri Fasal Bima Yojana (PMFBY), a government-sponsored crop insurance scheme in India. When implementing this endpoint, ensure compliance with:

Data Privacy: Adhere to India's Digital Personal Data Protection Act (DPDPA) for handling farmer personal information and mobile numbers

IRDAI Regulations: Follow Insurance Regulatory and Development Authority of India guidelines for digital insurance transactions

Government Scheme Rules: Comply with PMFBY operational guidelines issued by the Ministry of Agriculture & Farmers Welfare

Consent Management: Obtain explicit consent from applicants before processing their OTP verification and policy data

Data Retention: Implement appropriate data retention policies for OTP logs and verification records as per regulatory requirements

Audit Trails: Maintain comprehensive audit logs of all OTP verification attempts for compliance 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/pmfby/policy/submit-otp' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "pmfby_policy_blYspig", "otp": "123456" }'

{ "data": { "client_id": "pmfby_policy_blYspig", "otp_submitted": 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