Get EPFO Passbook

Endpoint Overview

POST /api/v1/income/epfo/passbook/get-passbook

Description

This API retrieves a user's Employee Provident Fund (EPF) passbook details using their client ID. It provides comprehensive information about the user's EPF contributions, including personal details, employer information, and a monthly breakdown of employee and employer contributions across different companies.

Key Benefits

Access complete EPF contribution history with monthly transaction details

Verify employment history across multiple organizations

Validate income patterns and financial stability through contribution records

Eliminate manual verification processes for EPF-related information

Use Cases

Financial Services

HR & Recruitment

Wealth Management

Verify income stability during loan underwriting processes

Validate employment history for credit assessment

Confirm regular EPF contributions as part of financial health checks

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 <token>`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
client_id	String	Yes	Unique identifier for the client whose EPF passbook details are being requested

Example Request

{
    "client_id": "{{client_id}}"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains all the EPF passbook information
data.client_id	String	Unique identifier for the client
data.pf_uan	String	Provident Fund Universal Account Number of the user
data.full_name	String	Full name of the EPF account holder
data.father_name	String	Father's name of the EPF account holder
data.dob	String	Date of birth of the EPF account holder (YYYY-MM-DD format)
data.companies	Object	Contains details of all companies where the user has EPF contributions
data.companies.[member_id]	Object	Company-specific details keyed by member ID
data.companies.[member_id].passbook	Array	List of monthly contribution entries
data.companies.[member_id].passbook[].member_id	String	Member ID for the specific company
data.companies.[member_id].passbook[].employee_share	String	Employee's contribution amount for the month
data.companies.[member_id].passbook[].employer_share	String	Employer's contribution amount for the month
data.companies.[member_id].passbook[].approved_on	String	Date when the contribution was approved (YYYY-MM-DD format)
data.companies.[member_id].passbook[].year	String	Year of the contribution
data.companies.[member_id].passbook[].month	String	Month of the contribution (in MM format)
data.companies.[member_id].company_name	String	Name of the employer company
data.companies.[member_id].establishment_id	String	Unique establishment ID of the company
status_code	Number	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Additional message (null if successful)
message_code	String	Code indicating the status of the request

Example Successful Response

{
    "data": {
        "client_id": "income_epfo_passbook_oYqZxyjYGXopbobRonZs",
        "pf_uan": "101550652226",
        "full_name": "JOHN DOE",
        "father_name": "JOHNY DOE",
        "dob": "1990-01-01",
        "companies": {
            "RJRAJ00161550000031234": {
                "passbook": [
                    {
                        "member_id": "RJRAJ00161550000031234",
                        "employee_share": "0",
                        "employer_share": "0",
                        "approved_on": "2019-04-01",
                        "year": "2019",
                        "month": "04"
                    },
                    {
                        "member_id": "RJRAJ00161550000031234",
                        "employee_share": "770",
                        "employer_share": "235",
                        "approved_on": "2020-01-14",
                        "year": "2020",
                        "month": "01"
                    },
                    {
                        "member_id": "RJRAJ00161550000031234",
                        "employee_share": "1848",
                        "employer_share": "598",
                        "approved_on": "2020-02-13",
                        "year": "2020",
                        "month": "02"
                    }
                    // Additional monthly entries omitted for brevity
                ],
                "company_name": "M/S ABC BANK LIMITED",
                "establishment_id": "RJRAJ0016112345"
            }
        }
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Possible Error Responses

Invalid Client ID

Authentication Error

{
    "data": null,
    "status_code": 400,
    "success": false,
    "message": "Invalid client_id provided",
    "message_code": "invalid_client_id"
}

This error occurs when the provided client ID is invalid or not found in the system.

Integration Best Practices

Security Recommendations

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

Implement token refresh mechanisms to handle token expiration

Use HTTPS for all API communications to ensure data encryption in transit

Implement proper error handling to avoid exposing sensitive information

User Experience Guidelines

Implement caching strategies to improve response times for frequently accessed passbook data

Display contribution history in a chronological format for better readability

Provide visual indicators for months with zero contributions

Calculate and display contribution totals to enhance user understanding

Code Samples

cURL

Python

Node.js

Related APIs

EPFO UAN Verification API: Verifies the validity of a UAN number

EPFO KYC Status API: Checks the KYC status of a UAN account

Income Verification API: Verifies income details through multiple sources

Compliance and Legal Considerations

When using this API, ensure you have proper consent from users to access their EPF data. The use of this API must comply with data privacy regulations such as the Personal Data Protection Bill and Information Technology Act. Ensure that you maintain appropriate data security measures and retention policies for any EPF data retrieved through this API.

{ "data": { "client_id": "income_epfo_passbook_oYqZxyjYGXopbobRonZs", "pf_uan": "101550652226", "full_name": "JOHN DOE", "father_name": "JOHNY DOE", "dob": "1990-01-01", "companies": { "RJRAJ00161550000031234": { "passbook": [ { "member_id": "RJRAJ00161550000031234", "employee_share": "0", "employer_share": "0", "approved_on": "2019-04-01", "year": "2019", "month": "04" }, { "member_id": "RJRAJ00161550000031234", "employee_share": "770", "employer_share": "235", "approved_on": "2020-01-14", "year": "2020", "month": "01" }, { "member_id": "RJRAJ00161550000031234", "employee_share": "1848", "employer_share": "598", "approved_on": "2020-02-13", "year": "2020", "month": "02" }, { "member_id": "RJRAJ00161550000031234", "employee_share": "1427", "employer_share": "437", "approved_on": "2020-03-12", "year": "2020", "month": "03" }, { "member_id": "RJRAJ00161550000031234", "employee_share": "1701", "employer_share": "520", "approved_on": "2020-04-13", "year": "2020", "month": "04" }, { "member_id": "RJRAJ00161550000031234", "employee_share": "1591", "employer_share": "486", "approved_on": "2020-05-13", "year": "2020", "month": "05" }, { "member_id": "RJRAJ00161550000031234", "employee_share": "1283", "employer_share": "392", "approved_on": "2020-06-12", "year": "2020", "month": "06" }, { "member_id": "RJRAJ00161550000031234", "employee_share": "690", "employer_share": "211", "approved_on": "2020-07-13", "year": "2020", "month": "07" }, { "member_id": "RJRAJ00161550000031234", "employee_share": "1803", "employer_share": "553", "approved_on": "2020-08-13", "year": "2020", "month": "08" }, { "member_id": "RJRAJ00161550000031234", "employee_share": "1540", "employer_share": "471", "approved_on": "2020-09-14", "year": "2020", "month": "09" }, { "member_id": "RJRAJ00161550000031234", "employee_share": "1485", "employer_share": "454", "approved_on": "2020-10-13", "year": "2020", "month": "10" }, { "member_id": "RJRAJ00161550000031234", "employee_share": "1697", "employer_share": "519", "approved_on": "2020-11-12", "year": "2020", "month": "11" }, { "member_id": "RJRAJ00161550000031234", "employee_share": "1591", "employer_share": "486", "approved_on": "2020-12-14", "year": "2020", "month": "12" } ], "company_name": "M/S ABC BANK LIMITED", "establishment_id": "RJRAJ0016112345" } } }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Get Passbook

Get EPFO Passbook#

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