Initialize

Endpoint Overview

POST /api/v1/epfo-async/establishment-name-to-details/initialize

Description

The EPFO Establishment Name to Details (Async) Initialize API allows you to look up detailed information about a registered EPFO (Employees' Provident Fund Organisation) establishment by its name. Because name-based searches may match multiple records and involve backend lookups against EPFO databases, this endpoint follows an asynchronous pattern — it accepts your request, registers it, and returns a client_id that you can use to poll for results.

By submitting an establishment name along with a configurable hit_size, you control how many matching records are retrieved. The API returns a unique client_id and a pending status, indicating the search has been queued and is being processed.

Key Benefits

Asynchronous Architecture: Handles potentially slow EPFO database lookups without blocking your application — initialize once, poll when ready.

Flexible Result Control: The hit_size parameter (1–10) lets you control the number of matching establishment records returned, keeping responses focused and relevant.

High Accuracy: Name-based lookup against live EPFO records ensures up-to-date establishment data for compliance and verification workflows.

Simple Integration: A single POST request with a minimal payload initializes the entire search flow, making integration fast and developer-friendly.

Use Cases

BFSI & Fintech

HR & Staffing

Insurance

Loan Underwriting: Verify employer establishment details during employee loan processing to confirm EPFO registration and legitimacy.

Due Diligence: Banks and NBFCs can validate corporate clients' EPFO registration status as part of KYC/KYB workflows.

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 in the format `Bearer <JWT_TOKEN>`. Use the token corresponding to your target environment (sandbox or production).
`Content-Type`	Yes	Must be `application/json`.

Request Body

Parameter	Type	Required	Description
`establishment_name`	String	Yes	The name of the EPFO-registered establishment to search for. Example: `"FIRST BANK LIMITED"`.
`hit_size`	Integer	Optional	The number of matching establishment records to retrieve. Accepted values: `1` to `10` (inclusive).

Example Request

{
    "establishment_name": "FIRST BANK LIMITED",
    "hit_size": 5
}

Process Response

Response Parameters

Parameter	Type	Description
`data`	Object	Top-level container for the response payload.
`data.client_id`	String	A unique identifier for this async request. Use this `client_id` to poll the status/result endpoint.
`data.establishment_name`	String	The establishment name as submitted in the request, echoed back for confirmation.
`data.hit_size`	Integer	The `hit_size` value as submitted in the request, echoed back for confirmation.
`data.status`	String	Current processing status of the async request. On initialization, this will always be `"pending"`.
`status_code`	Integer	HTTP-equivalent status code for the operation. `200` indicates the request was accepted successfully.
`success`	Boolean	`true` if the initialization request was accepted and queued successfully; `false` otherwise.
`message`	String	A human-readable summary of the response outcome. Example: `"Success"`.
`message_code`	String	A machine-readable code representing the response outcome. Example: `"success"`.

Example Successful Response

{
    "data": {
        "client_id": "establishment_name_to_details_async_qShvUrsPSmpdYmwckaPt",
        "establishment_name": "FIRST BANK LIMITED",
        "hit_size": 5,
        "status": "pending"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

401 Unauthorized

400 Bad Request

500 Internal Server Error

{
    "status_code": 401,
    "success": false,
    "message": "Authentication credentials were not provided or are invalid.",
    "message_code": "authentication_failed"
}

Returned when the Authorization header is missing, the JWT token is malformed, expired, or does not match the target environment (sandbox vs. production).

Integration Best Practices

Security Recommendations

Environment Isolation: Always use the sandbox environment (https://sandbox.surepass.app) for development and testing. Never use production tokens in non-production systems.

Token Storage: Store your JWT tokens securely using environment variables or a secrets manager. Never hard-code tokens in source code or commit them to version control.

Token Rotation: Periodically rotate your JWT tokens and revoke any tokens that may have been compromised.

Transport Security: All API requests must be made over HTTPS. Never send tokens or request bodies over plain HTTP.

Minimal Scope: Use API credentials with only the permissions required for this integration. Avoid using highly privileged tokens where a scoped token suffices.

Async Workflow Guidelines

Store the client_id: After a successful initialization, persist the returned client_id immediately — it is the only way to retrieve the results of your async query.

Poll Responsibly: When polling the status/result endpoint using the client_id, implement a reasonable polling interval (e.g., 2–5 seconds) with a maximum retry limit to avoid overwhelming the API.

Handle pending Status Gracefully: The "pending" status on initialization is expected and normal. Design your application flow to wait and retry rather than treating it as an error.

Validate hit_size: Choose a hit_size appropriate to your use case. A smaller value (e.g., 1–3) is suitable when you expect an exact match; a larger value (up to 10) is better when the name may have variations or duplicates.

Log client_id for Auditing: For compliance and debugging purposes, log the client_id alongside the request timestamp and establishment_name in your system.

Code Samples

cURL

Python

Node.js

Related APIs

EPFO Async — Establishment Name to Details (Status/Result): Use the client_id from this Initialize endpoint to poll for the processing status and fetch the final establishment details once ready.

EPFO UAN to Details: Retrieve detailed employee and employer information using a Universal Account Number (UAN) for direct, identifier-based EPFO lookups.

Company to EPFO Details: Look up EPFO establishment records associated with a registered company name or CIN for corporate verification workflows.

Compliance and Legal Considerations

Data Privacy: Establishment data retrieved via this API originates from EPFO's publicly accessible records. Ensure that your use of this data complies with applicable data protection regulations, including the Digital Personal Data Protection Act (DPDP), 2023 in India.

Purpose Limitation: This API should be used exclusively for legitimate business purposes such as KYC, KYB, employee verification, or regulatory compliance. Unauthorized or bulk harvesting of EPFO data may violate EPFO's terms of use and applicable law.

Audit Trails: Maintain logs of all API calls, including timestamps and the business purpose, to demonstrate compliance in the event of an audit.

Third-Party Sharing: Do not share or resell raw establishment data obtained via this API to unauthorized third parties without appropriate legal basis and consent.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location 'https://kyc-api.surepass.app/api/v1/epfo-async/establishment-name-to-details/initialize' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "establishment_name": "FIRST BANK LIMITED" }'

{ "data": { "client_id": "establishment_name_to_details_async_qShvUrsPSmpdYmwckaPt", "establishment_name": "FIRST BANK LIMITED", "hit_size": 5, "status": "pending" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

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