Submit EPFO OTP

Endpoint Overview

POST /api/v1/income/epfo/passbook/submit-otp

Description

This API endpoint allows you to submit the OTP (One-Time Password) received during the EPFO (Employees' Provident Fund Organisation) passbook verification process. After initiating an EPFO passbook verification request, this endpoint validates the OTP sent to the user's registered mobile number, enabling secure access to their EPFO passbook data.

Key Benefits

Secure verification through OTP validation for accessing sensitive EPFO data

Simple request structure requiring minimal parameters

Clear response indicating validation status

Seamless integration with other EPFO passbook retrieval APIs

Use Cases

Financial Services

HR & Recruitment

Wealth Management

Verify employment history and income details for loan approval processes

Automate income verification for credit card applications

Validate employment tenure for financial product eligibility

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.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	JWT Bearer token for authentication. Format: `Bearer <your_token>`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
client_id	String	Yes	Your unique client identifier provided by Surepass
otp	String	Yes	The 6-digit OTP received on the user's registered mobile number

Example Request

{
    "client_id": "{{client_id}}",
    "otp": "582430"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the validation result
data.otp_validated	Boolean	Indicates whether the OTP was successfully validated
status_code	Integer	HTTP status code of the response
message_code	String	Brief status message code
message	String or null	Detailed message (if applicable)
success	Boolean	Overall success status of the request

Example Successful Response

{
    "data": {
        "otp_validated": true
    },
    "status_code": 200,
    "message_code": "success",
    "message": null,
    "success": true
}

Possible Error Responses

Invalid OTP

Authentication Error

{
    "data": {
        "otp_validated": false
    },
    "status_code": 400,
    "message_code": "invalid_otp",
    "message": "The OTP provided is invalid or has expired",
    "success": false
}

The OTP provided is incorrect or has expired. Users typically have a limited time window to submit the OTP.

Integration Best Practices

Security Recommendations

Store client credentials securely and never expose them in client-side code

Implement proper error handling to manage failed OTP validations gracefully

Set appropriate timeouts for API calls to handle network latency

Implement rate limiting on your end to prevent abuse of the OTP submission process

User Experience Guidelines

Clearly communicate to users that they will receive an OTP on their registered mobile number

Provide a simple and intuitive interface for OTP entry

Implement a resend OTP option in case the user doesn't receive the initial OTP

Display clear error messages when OTP validation fails

Code Samples

cURL

Python

Node.js

Related APIs

EPFO Passbook Initialization API: Initiates the EPFO passbook verification process

EPFO Passbook Data Retrieval API: Fetches the passbook data after successful OTP validation

EPFO Employment History API: Retrieves employment history from EPFO records

Compliance and Legal Considerations

The EPFO data accessed through this API contains sensitive personal and financial information. Ensure you have explicit user consent before accessing this data and comply with all applicable data protection regulations including the Information Technology Act, 2000 and the Personal Data Protection Bill. Store and process this data in accordance with security best practices and data protection laws.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/income/epfo/passbook/submit-otp' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "{{client_id}}", "otp": "582430" }'

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Submit EPFO OTP

Submit EPFO OTP#

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

Submit EPFO OTP

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples