Initialize

Endpoint Overview

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

Description

The EPFO Establishment Details Initialize API initiates an asynchronous request to fetch comprehensive establishment details registered under the Employees' Provident Fund Organisation (EPFO). By submitting a valid establishment_id, this endpoint queues a background job and returns a client_id that can be used to poll for results once processing is complete.

This API follows an async pattern — the initialization call is lightweight and fast, while the actual data retrieval happens in the background. This design ensures reliability and avoids timeout issues when dealing with government data sources that may have variable response times.

Key Benefits

Non-blocking Architecture: Decouples the request from the response, preventing timeouts on slow upstream EPFO systems.

Scalable Integration: Enables high-throughput workflows by allowing multiple establishments to be queried in parallel.

Reliable Tracking: Returns a unique client_id per request, allowing precise status tracking and result retrieval.

Dual Environment Support: Separate sandbox and production base URLs allow safe development and testing before going live.

Use Cases

HR & Payroll

Lending & Finance

Legal & Compliance

Verify EPFO registration status of a new vendor or contractor before onboarding them.

Automate bulk compliance checks across all registered establishments in a payroll system.

Cross-validate establishment IDs submitted by employees during onboarding against official EPFO records.

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 authentication. Format: `Bearer <JWT_TOKEN>`
`Content-Type`	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
`establishment_id`	String	Yes	The unique EPFO establishment identifier (e.g., `DLCPM0001014111`). This is the alphanumeric code assigned to a registered employer by EPFO.

Example Request

{
    "establishment_id": "DLCPM0001014111"
}

Process Response

Response Parameters

Parameter	Type	Description
`data`	Object	Container object holding the result payload.
`data.client_id`	String	Unique identifier for this async job. Use this value to poll the status or retrieve results from the corresponding fetch endpoint.
`data.establishment_id`	String	The establishment ID that was submitted in the request, echoed back for confirmation.
`data.status`	String	Current processing state of the async job. Returns `"pending"` on successful initialization, indicating the background job has been queued.
`status_code`	Integer	HTTP-equivalent status code for the API response (e.g., `200` for success).
`success`	Boolean	Indicates whether the request was accepted and queued successfully. `true` means the async job was initialized.
`message`	String	Human-readable description of the response outcome (e.g., `"Success"`).
`message_code`	String	Machine-readable code corresponding to the response message (e.g., `"success"`). Useful for programmatic handling of response states.

Example Successful Response

{
    "data": {
        "client_id": "establishment_details_async_oNNiOnwngacfhtyycnsw",
        "establishment_id": "DLCPM0001014111",
        "status": "pending"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

401 Unauthorized

400 Bad Request

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

Returned when the Authorization header is missing, malformed, or the JWT token is expired or invalid. Ensure you are passing a valid Bearer token for the correct environment (sandbox vs. production).

Integration Best Practices

Security Recommendations

Never expose JWT tokens in client-side code, version control systems, or logs. Store tokens securely using environment variables or secrets management tools.

Use separate tokens for sandbox and production environments to minimize risk of accidental production access during development.

Rotate tokens periodically and immediately revoke any token suspected of being compromised.

Validate HTTPS: Always use the provided HTTPS base URLs. Never send credentials over unencrypted HTTP connections.

Restrict token scope: Provision API tokens with the minimum required permissions to follow the principle of least privilege.

Async Workflow Guidelines

Store the client_id returned from this endpoint immediately and persistently — it is required to retrieve the result from the corresponding fetch/status endpoint.

Implement polling with backoff: After initialization, poll the result endpoint at increasing intervals (e.g., 2s, 4s, 8s) rather than hammering the API continuously.

Handle pending gracefully: A "status": "pending" response is expected and normal; build your UI or workflow to inform users that processing is underway.

Set timeouts: Define a maximum polling duration in your application to handle edge cases where a job takes unexpectedly long or fails silently.

Log client_id and establishment_id together for each request to simplify debugging and support tracing.

Code Samples

cURL

Python

Node.js

Related APIs

EPFO Establishment Details - Fetch Result: Use the client_id returned from this endpoint to retrieve the completed establishment details once the async job status moves from pending to a terminal state.

EPFO Member Passbook Async - Initialize: Similar async pattern for initiating passbook data retrieval for individual EPFO members using their UAN.

EPFO Member Profile Async - Initialize: Initiates an async request to fetch member profile information registered with EPFO.

EPFO Async Status Check: A general-purpose status polling endpoint to check the current processing state of any async job using its client_id.

Compliance and Legal Considerations

Data Privacy: Establishment details retrieved via this API may include sensitive business and employee-count information. Ensure your application complies with applicable data protection regulations, including the Digital Personal Data Protection Act (DPDPA) in India, before storing or sharing this data.

Authorized Use Only: This API must only be used with explicit consent from the establishment owner or their authorized representative. Unauthorized querying of third-party establishment data without consent may violate applicable laws.

Data Retention: Do not retain establishment data for longer than operationally necessary. Define and enforce data retention and deletion policies within your system.

Audit Logging: Maintain logs of all API calls including the requester identity, timestamp, and establishment_id queried to support regulatory audits and internal compliance reviews.

EPFO Data Terms: Usage of EPFO data is subject to the terms and conditions set by the Employees' Provident Fund Organisation. Ensure your use case aligns with permissible purposes under applicable labour and social security laws.

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-details/initialize' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "establishment_id": "DLCPM0001014111" }'

{ "data": { "client_id": "establishment_details_async_oNNiOnwngacfhtyycnsw", "establishment_id": "DLCPM0001014111", "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