Finpass API Collection
  1. EPFO
  • Introduction
  • Bureau
    • Commercial Credit Report
      POST
    • Multi-Bureau Fetch
      POST
  • Bank Statement Analyser
    • Batch Upload Statements
      POST
    • Batch Result
      GET
    • Upload Statement
      POST
    • Statement Result
      GET
  • Account Aggregator
    • Initialize
      POST
    • Fetch JSON Report
      POST
    • Fetch PDF Report
      POST
    • Refresh Data
      POST
  • Corporate
    • CIN Lookup
      POST
    • LLPIN
      POST
    • PAN Lookup
      POST
    • Company Autocomplete
      POST
  • EPFO
    • Fetch EPFO Data by Mobile Number
      POST
    • EPFO-CRIF Combined Report
      POST
  • ITR Analyzer
    • Initialize
      POST
    • Status
      POST
    • ITR Analyzer — Get Full Data
      POST
    • Create ITR Login Client
      POST
    • Check Credential
      POST
    • Generate 2FA
      POST
    • Submit 2FA OTP
      POST
    • Initiate ITR Password Reset
      POST
    • Confirm Password Reset (Submit OTP)
      POST
  • AA-BSA Analyzer
    • Initialize
    • Status
    • AA BSA — Statement Result
    • AA BSA — Analysis JSON
  • GST Analyser
    • Analyze
    • Status
    • GST Data
  • Hosted Collection
    • Create ITR Collection Session
    • Create GST Collection Session
  1. EPFO

Fetch EPFO Data by Mobile Number

POST
/api/v1/services/epfo-combined/fetch

Fetch EPFO Data by Mobile Number#

Endpoint Overview
POST /api/v1/services/epfo-combined/fetch

Description#

The Fetch EPFO Data by Mobile Number API retrieves a taxpayer's consolidated Employees' Provident Fund Organisation (EPFO) records using just their registered mobile number. The endpoint queries the EPFO ecosystem, aggregates employer history, contribution timelines, UAN linkages, and member profile data, and returns it in a single structured response — without CRIF bureau enrichment.
This is a synchronous, single-call workflow: provide a mobile number, receive the EPFO profile. It is the fastest way to verify employment history and PF contribution patterns for individuals whose mobile number is linked to their UAN.
Key Benefits
Single-Call Simplicity — No multi-step orchestration, polling, or job IDs to manage.
Mobile-First Lookup — Works with just a registered mobile number; no UAN or PAN required upfront.
Consolidated Employment View — Returns aggregated employer history and contribution trail in one payload.
No Bureau Dependency — Faster, lighter response without CRIF enrichment overhead.

Use Cases#

Lending & NBFC
HR Tech & Background Verification
Insurance & Wealth
Verify salaried borrower employment continuity and tenure during loan underwriting.
Validate stated employer and income against EPFO contribution records.
Detect job switches or contribution gaps that may affect credit risk decisions.

Technical Implementation#

1
Authentication
All API requests require authentication using API key headers. Authentication follows these steps:
1.
Obtain API Credentials: Register with Finpass to receive your X-API-Key and X-API-Secret.
2.
Include in Requests: Add both headers to every request — X-API-Key: <your_key> and X-API-Secret: <your_secret>.
3.
Use Environment-Specific Credentials: Use separate keys for sandbox and production.
The production environment base URL is:
Production: https://api.finpass.ai
Never expose API credentials in client-side code; always proxy requests through your backend.
2
Request Parameters

Request Headers#

HeaderRequiredDescription
X-API-KeyYesYour Finpass-issued API key.
X-API-SecretYesYour Finpass-issued API secret paired with the key.
Content-TypeYesMust be set to application/json.

Request Body#

ParameterTypeRequiredDescription
mobile_numberstringYesThe 10-digit Indian mobile number registered against the taxpayer's UAN / EPFO profile.

Example Request#

{
  "mobile_number": "9999999999"
}
3
Process Response

Response Parameters#

ParameterTypeDescription
successbooleanIndicates whether the EPFO data was retrieved successfully.
dataobjectContainer holding the consolidated EPFO payload.
data.mobile_numberstringThe mobile number queried.
data.uanstringThe Universal Account Number linked to the mobile, when available.
data.member_profileobjectMember-level identity and demographic details from EPFO.
data.employment_historyarrayList of employers with PF establishment IDs, join/exit dates, and tenure.
data.contribution_summaryobjectAggregated contribution metrics across employers.
data.passbookarrayPeriod-wise contribution entries (employee, employer, and pension shares).
messagestringHuman-readable confirmation or contextual note.

Example Successful Response#

{
  "success": true,
  "data": {
    "mobile_number": "9999999999",
    "uan": "100000000000",
    "member_profile": { },
    "employment_history": [ ],
    "contribution_summary": { },
    "passbook": [ ]
  },
  "message": "EPFO data retrieved successfully."
}

Possible Error Responses#

No EPFO Record
Unauthorized
Validation Error
Upstream Unavailable
Rate Limited
{
  "success": false,
  "error": {
    "code": "EPFO_RECORD_NOT_FOUND",
    "message": "No EPFO profile is linked to the supplied mobile number."
  }
}
Returned when the mobile number is not linked to any UAN or EPFO member profile. Verify the number with the user and confirm it is the one registered with their employer.

Integration Best Practices#

Security Recommendations
Always invoke this endpoint over HTTPS and validate TLS certificates.
Treat X-API-Key and X-API-Secret as highly sensitive secrets; rotate them periodically and store them in a secure secret manager.
Treat the returned uan, employment_history, and passbook data as sensitive personal information; encrypt at rest and restrict access.
Never expose raw EPFO responses to untrusted clients; apply server-side authorization before forwarding any data.
Use separate API credentials for sandbox and production environments.
User Experience Guidelines
Validate mobile number format and country code on the client side before submission.
Display a clear consent screen explaining that EPFO records will be fetched using the supplied mobile number.
When EPFO_RECORD_NOT_FOUND is returned, guide the user to verify the registered mobile number with their employer rather than retrying blindly.
Surface a concise summary (current employer, tenure, total contribution) before deep-diving into the full passbook.
Cache responses for a short, well-defined window to avoid redundant upstream calls within the same session.

Code Samples#

cURL
Python
Node.js
Related APIs
EPFO Combined with CRIF Enrichment — Companion endpoint that augments EPFO data with CRIF bureau insights for richer underwriting.
UAN Lookup — Resolves a UAN directly from PAN or other identifiers when mobile-based lookup is not viable.
Employment Verification — Standalone employer-confirmation API for cases where full EPFO history is not required.
Compliance and Legal Considerations
EPFO records contain sensitive personal and employment information governed by India's Employees' Provident Funds and Miscellaneous Provisions Act, 1952, the Information Technology Act, 2000, and the Digital Personal Data Protection Act, 2023 (DPDP Act). Integrators must obtain explicit, informed, and revocable consent from the individual whose data is being fetched before invoking this endpoint, and must clearly disclose the purposes for which the data will be used. Maintain a documented data retention and deletion policy aligned with the consent scope, restrict access on a need-to-know basis, log access for audit purposes, and provide the individual with rights to review and request deletion of their data.

Request

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200Success
application/json
Bodyapplication/json

Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api.finpass.ai/api/v1/services/epfo-combined/fetch' \
--header 'x-api-key;' \
--header 'x-api-secret;' \
--header 'Content-Type: application/json' \
--data '{
    "mobile_number": "9999999999"
}'
Response Response Example
{}
Previous
Company Autocomplete
Next
EPFO-CRIF Combined Report
Built with