Generate EPFO OTP

Endpoint Overview

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

Description

This API endpoint initiates the OTP generation process for accessing EPFO (Employees' Provident Fund Organisation) passbook details. It sends a one-time password to the mobile number registered with the EPFO account, which is required for subsequent authentication and data retrieval operations. The endpoint is part of Surepass's Income Verification suite, enabling secure access to official EPFO records for income verification purposes.

Key Benefits

Secure access to official EPFO records through OTP-based authentication

Simplified integration with India's largest employee provident fund database

Real-time verification of employment and income details

Compliant with regulatory requirements for accessing government records

Use Cases

Financial Services

HR & Recruitment

Fintech

Loan eligibility assessment based on verified employment history

Credit underwriting with verified income data

Automated income verification for mortgage applications

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
id_number	String	Yes	The Universal Account Number (UAN) of the EPFO account holder

Example Request

{
    "id_number": "100000000000"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the response data
data.client_id	String	Unique identifier for the current session/request
data.otp_sent	Boolean	Indicates whether OTP was successfully sent
data.masked_mobile_number	String	Partially masked mobile number where OTP was sent
status_code	Integer	HTTP status code of the response
message_code	String	Short code indicating the response status
message	String	Human-readable description of the response
success	Boolean	Overall success status of the request

Example Successful Response

{
    "data": {
        "client_id": "income_epfo_passbook_zTqOxnWwQFXgbzxpaUeh",
        "otp_sent": true,
        "masked_mobile_number": "XXXXXX5699"
    },
    "status_code": 200,
    "message_code": "success",
    "message": "OTP Sent.",
    "success": true
}

Possible Error Responses

Invalid UAN

Service Unavailable

Authentication Error

{
    "data": null,
    "status_code": 400,
    "message_code": "invalid_input",
    "message": "Invalid UAN provided. Please check and try again.",
    "success": false
}

This error occurs when the provided UAN is not valid or does not exist in the EPFO database.

Integration Best Practices

Security Recommendations

Store the client_id securely as it's required for subsequent API calls

Implement proper error handling to manage failed OTP deliveries

Use environment-specific endpoints (sandbox/production) with appropriate credentials

Implement request timeout handling as EPFO services may occasionally experience delays

User Experience Guidelines

Clearly inform users that they will receive an OTP on their EPFO-registered mobile number

Display the masked mobile number to help users identify where to expect the OTP

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

Provide clear error messages that guide users toward resolution

Code Samples

cURL

Python

Node.js

Related APIs

EPFO Passbook Verify OTP: Validates the OTP received on the registered mobile number

EPFO Passbook Fetch Details: Retrieves the EPFO passbook details after OTP verification

EPFO Passbook Download: Downloads the EPFO passbook in PDF format

Compliance and Legal Considerations

Access to EPFO data is governed by Indian data protection regulations. Ensure you have explicit user consent before accessing their EPFO information. The data retrieved should only be used for the specific purpose disclosed to and authorized by the user. Storing EPFO credentials or permanent access tokens is not permitted.

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/income/epfo/passbook/generate-otp' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "id_number": "{{id_number}}" }'

{ "data": { "client_id": "income_epfo_passbook_zTqOxnWwQFXgbzxpaUeh", "otp_sent": true, "masked_mobile_number": "XXXXXX5699" }, "status_code": 200, "message_code": "success", "message": "OTP Sent.", "success": true }

Generate EPFO OTP

Generate 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

Generate 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