EPFO Passbook Underwriting Status

Endpoint Overview

POST /api/v1/underwriting/epfo-passbook-underwriting/status

Description

The EPFO Passbook Underwriting Status API enables you to retrieve comprehensive employment and income verification data from the Employees' Provident Fund Organisation (EPFO) passbook. This endpoint provides detailed contribution history, personal information, and calculated gross income metrics essential for underwriting and loan assessment processes.

This API delivers structured data including employee contributions, employer contributions, pension share details, and automatically calculates gross income based on 12-month contribution history. The response includes personal identifiers such as UAN, name, date of birth, and father's name, making it ideal for comprehensive employment and income verification workflows.

Key Benefits

Automated Income Calculation: Automatically computes gross income from 12-month contribution history, eliminating manual calculations

Comprehensive Employment History: Access detailed monthly contribution records with employee, employer, and pension components

Real-time Verification: Retrieve up-to-date EPFO passbook data for accurate underwriting decisions

Flexible Report Formats: Choose between URL-based document access or Base64-encoded reports for seamless integration

Use Cases

Financial Services

Insurance

Background Verification

Loan Underwriting: Verify employment stability and income levels for personal, home, or business loan applications

Credit Assessment: Validate income claims during credit card or line of credit evaluations

Income Verification: Confirm salary details for loan-to-income ratio calculations

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 EPFO passbook underwriting request (e.g., `epfo_passbook_underwriting_xaFPmACIdbp`)
get_report_base64	boolean	No	Optional flag to retrieve the report data in Base64 format. If `true`, the response includes `base64_report` field. If `false` or omitted, only `document_url` is provided

Example Request

{
    "client_id": "epfo_passbook_underwriting_xaFPmACIdbp",
    "get_report_base64": true
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object holding all response data
data.client_id	string	Unique identifier for the underwriting request
data.mobile_number	string	Mobile number associated with the EPFO account
data.uan	string	Universal Account Number (12-digit unique identifier for EPFO member)
data.full_name	string	Full name of the EPFO account holder
data.dob	string	Date of birth in YYYY-MM-DD format
data.father_name	string	Father's name as registered in EPFO records
data.employee_contribution	array	Array of monthly contribution records, each containing year, month, employee_share, employer_share, pension_share, and approved_on date
data.gross_income	number/null	Calculated gross annual income if 12 months of contribution data is available
data.expected_gross_income	number/null	Projected gross annual income if less than 12 months of contribution data is available
data.document_url	string	Pre-signed S3 URL to download the EPFO passbook report PDF (expires in 600 seconds)
data.base64_report	string/null	Base64-encoded report data (only populated if `get_report_base64` is `true`)
data.status	string	Overall status of the underwriting request (e.g., "completed")
data.mobile_to_uan_status	string	Status of mobile number to UAN mapping (e.g., "success")
data.epfo_passbook_init_status	string	Status of EPFO passbook initialization (e.g., "success")
data.epfo_passbook_download_status	string	Status of EPFO passbook download (e.g., "success")
status_code	integer	HTTP status code (200 for success)
success	boolean	Indicates whether the request was successful
message	string	Human-readable message describing the result
message_code	string	Machine-readable message code for programmatic handling

Example Successful Response

{
    "data": {
        "client_id": "epfo_passbook_underwriting_xaFPmACIdbp",
        "mobile_number": "9876543210",
        "uan": "123456789012",
        "full_name": "RAJIV TALWAR",
        "dob": "1990-01-01",
        "father_name": "SANJEEV TALWAR",
        "employee_contribution": [
            {
                "year": 2023,
                "month": 12,
                "employee_share": 1800,
                "employer_share": 550,
                "pension_share": 1250,
                "approved_on": "2023-12-15"
            },
            {
                "year": 2023,
                "month": 11,
                "employee_share": 1800,
                "employer_share": 550,
                "pension_share": 1250,
                "approved_on": "2023-11-13"
            },
            {
                "year": 2023,
                "month": 10,
                "employee_share": 1800,
                "employer_share": 550,
                "pension_share": 1250,
                "approved_on": "2023-10-14"
            },
            {
                "year": 2023,
                "month": 9,
                "employee_share": 1800,
                "employer_share": 550,
                "pension_share": 1250,
                "approved_on": "2023-09-13"
            },
            {
                "year": 2023,
                "month": 8,
                "employee_share": 1800,
                "employer_share": 550,
                "pension_share": 1250,
                "approved_on": "2023-08-15"
            },
            {
                "year": 2023,
                "month": 7,
                "employee_share": 1800,
                "employer_share": 550,
                "pension_share": 1250,
                "approved_on": "2023-07-15"
            },
            {
                "year": 2023,
                "month": 6,
                "employee_share": 1800,
                "employer_share": 550,
                "pension_share": 1250,
                "approved_on": "2023-06-28"
            },
            {
                "year": 2023,
                "month": 5,
                "employee_share": 1800,
                "employer_share": 550,
                "pension_share": 1250,
                "approved_on": "2023-05-20"
            },
            {
                "year": 2023,
                "month": 4,
                "employee_share": 1800,
                "employer_share": 550,
                "pension_share": 1250,
                "approved_on": "2023-04-17"
            },
            {
                "year": 2023,
                "month": 3,
                "employee_share": 1800,
                "employer_share": 550,
                "pension_share": 1250,
                "approved_on": "2023-03-12"
            },
            {
                "year": 2023,
                "month": 2,
                "employee_share": 1800,
                "employer_share": 550,
                "pension_share": 1250,
                "approved_on": "2023-02-12"
            },
            {
                "year": 2023,
                "month": 1,
                "employee_share": 1800,
                "employer_share": 550,
                "pension_share": 1250,
                "approved_on": "2023-01-19"
            }
        ],
        "gross_income": 359856,
        "expected_gross_income": null,
        "document_url": "https://aadhaar-kyc-docs.s3.amazonaws.com/shikhar/epfo_passbook_underwriting/epfo_passbook_underwriting_raxktAUTlyGQsRhOofkS/report_1769520588374113.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20260127%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20260127T132948Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=9e78569a63ea568fd5927fd0a5124479c0d9d5145f5a16563060d61df30858fa",
        "base64_report": null,
        "status": "completed",
        "mobile_to_uan_status": "success",
        "epfo_passbook_init_status": "success",
        "epfo_passbook_download_status": "success"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Client ID

Authentication Error

Processing Incomplete

Server Error

{
    "data": null,
    "status_code": 404,
    "success": false,
    "message": "Client ID not found",
    "message_code": "client_id_not_found"
}

This error occurs when the provided client_id does not exist in the system or has been incorrectly formatted.

Integration Best Practices

Security Recommendations

Secure Token Storage: Store JWT tokens securely using environment variables or secure vault services, never hard-code them in your application

Token Rotation: Implement automatic token refresh mechanisms to handle token expiration gracefully

HTTPS Only: Always use HTTPS connections to prevent token interception during transmission

Document URL Handling: Note that document_url expires in 600 seconds (10 minutes); download or process documents immediately upon receipt

PII Protection: Handle personally identifiable information (name, DOB, UAN, mobile number) in compliance with data protection regulations

Access Control: Implement role-based access control to restrict who can initiate underwriting requests and view sensitive data

User Experience Guidelines

Status Polling: Implement intelligent polling with exponential backoff when checking request status to avoid overwhelming the API

Progress Indication: Display clear status indicators to users showing the stages: mobile-to-UAN mapping, passbook initialization, and download

Error Handling: Provide user-friendly error messages when verification fails, guiding users on next steps

Income Display: Clearly distinguish between gross_income (12-month actual) and expected_gross_income (projected) in your UI

Document Access: Provide users with immediate access to download the PDF report while the URL is valid

Consent Management: Ensure proper user consent is obtained before initiating EPFO data retrieval

Code Samples

cURL

Python

Node.js

Compliance and Legal Considerations

This API accesses sensitive personal and financial information from EPFO records. Ensure compliance with the following:

User Consent: Obtain explicit user consent before accessing EPFO passbook data, as required by data protection regulations

Data Privacy: Handle all retrieved data in accordance with the Information Technology Act, 2000 and Personal Data Protection Bill requirements

Purpose Limitation: Use EPFO data only for stated purposes (underwriting, income verification) and not for unauthorized secondary uses

Data Retention: Implement appropriate data retention policies and securely delete EPFO data when no longer needed

Audit Trail: Maintain comprehensive audit logs of all EPFO data access for regulatory compliance

KYC Compliance: This API supports Know Your Customer (KYC) requirements for financial institutions as per RBI guidelines

Employment Records: EPFO data is official government records and should be treated with appropriate confidentiality

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/underwriting/epfo-passbook-underwriting/status' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "epfo_passbook_underwriting_xaFPmACIdbp" }'

{ "data": { "client_id": "epfo_passbook_underwriting_xaFPmACIdbp", "uan": "123456789012", "full_name": "RAJIV TALWAR", "dob": "1990-01-01", "father_name": "SANJEEV TALWAR", "employee_contribution": [ { "year": 2023, "month": 12, "employee_share": 1800, "employer_share": 550, "pension_share": 1250, "approved_on": "2023-12-15" }, { "year": 2023, "month": 11, "employee_share": 1800, "employer_share": 550, "pension_share": 1250, "approved_on": "2023-11-13" }, { "year": 2023, "month": 10, "employee_share": 1800, "employer_share": 550, "pension_share": 1250, "approved_on": "2023-10-14" }, { "year": 2023, "month": 9, "employee_share": 1800, "employer_share": 550, "pension_share": 1250, "approved_on": "2023-09-13" }, { "year": 2023, "month": 8, "employee_share": 1800, "employer_share": 550, "pension_share": 1250, "approved_on": "2023-08-15" }, { "year": 2023, "month": 7, "employee_share": 1800, "employer_share": 550, "pension_share": 1250, "approved_on": "2023-07-15" }, { "year": 2023, "month": 6, "employee_share": 1800, "employer_share": 550, "pension_share": 1250, "approved_on": "2023-06-28" }, { "year": 2023, "month": 5, "employee_share": 1800, "employer_share": 550, "pension_share": 1250, "approved_on": "2023-05-20" }, { "year": 2023, "month": 4, "employee_share": 1800, "employer_share": 550, "pension_share": 1250, "approved_on": "2023-04-17" }, { "year": 2023, "month": 3, "employee_share": 1800, "employer_share": 550, "pension_share": 1250, "approved_on": "2023-03-12" }, { "year": 2023, "month": 2, "employee_share": 1800, "employer_share": 550, "pension_share": 1250, "approved_on": "2023-02-12" }, { "year": 2023, "month": 1, "employee_share": 1800, "employer_share": 550, "pension_share": 1250, "approved_on": "2023-01-19" } ], "gross_income": 359856, "expected_gross_income": null, "document_url": "https://aadhaar-kyc-docs.s3.amazonaws.com/shikhar/epfo_passbook_underwriting/epfo_passbook_underwriting_raxktAUTlyGQsRhOofkS/report_1769520588374113.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20260127%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20260127T132948Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=9e78569a63ea568fd5927fd0a5124479c0d9d5145f5a16563060d61df30858fa", "base64_report": null, "status": "completed", "mobile_to_uan_status": "success", "epfo_passbook_init_status": "success", "epfo_passbook_download_status": "success" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Status

EPFO Passbook Underwriting Status#

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