EPFO Passbook Init

Endpoint Overview

POST /api/v1/epfo-passbook-advanced/init

Description

The EPFO Passbook Init API initiates the process of retrieving an employee's EPFO (Employees' Provident Fund Organisation) passbook details. This endpoint takes a UAN (Universal Account Number) and generates a unique client ID that will be used in subsequent API calls to fetch the actual passbook data. This is the first step in a two-part process designed to securely access and retrieve official EPFO passbook information.

Key Benefits

Simplified access to official EPFO passbook data through a secure API

Streamlined verification of employment history and PF contributions

Reduced manual effort in collecting and verifying EPFO records

Real-time initialization of the passbook retrieval process

Use Cases

Financial Services

HR & Payroll

Fintech

Loan eligibility verification based on employment history and PF contributions

Credit risk assessment using consistent employment and contribution records

Automated income verification for mortgage and personal loan 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_JWT_TOKEN`)
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
id_number	String	Yes	UAN (Universal Account Number) of the employee whose EPFO passbook details are to be retrieved

Example Request

{
    "id_number": "100584579999"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the response data
data.client_id	String	Unique identifier to be used in subsequent API calls to retrieve EPFO passbook details
status_code	Integer	HTTP status code indicating the result of the request
success	Boolean	Indicates whether the request was successful
message	String	Human-readable description of the response status
message_code	String	Machine-readable code representing the response status

Example Successful Response

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

Possible Error Responses

Invalid UAN

Authentication Error

{
    "status_code": 400,
    "success": false,
    "message": "Invalid UAN number format",
    "message_code": "invalid_uan_format"
}

The provided UAN number is not in the correct format or contains invalid characters.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement proper error handling to avoid exposing sensitive information

Validate the UAN number format before making API calls

Implement rate limiting on your end to prevent abuse

User Experience Guidelines

Display a loading indicator while the initialization is in progress

Clearly communicate to users that this is step 1 of a 2-step process

Store the client_id securely for the subsequent API call

Implement proper error messages that guide users on how to resolve issues

Code Samples

cURL

Python

Node.js

Related APIs

EPFO Passbook Status API: Used to retrieve the actual passbook details using the client_id obtained from this API

EPFO UAN Verification API: Validates the existence and status of a UAN number

EPFO KYC Status API: Checks the KYC status of an EPFO account

Compliance and Legal Considerations

The use of this API must comply with EPFO data usage policies and privacy regulations. Ensure you have proper consent from users before accessing their EPFO data. The data retrieved should be used only for legitimate business purposes and stored in compliance with data protection regulations.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

EPFO Passbook Init

EPFO Passbook Init#

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

EPFO Passbook Init

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples