Status

Endpoint Overview

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

Description

The EPFO Establishment Name to Details (Async) — Status endpoint allows you to poll and retrieve the result of a previously initiated asynchronous EPFO lookup request. After submitting an establishment name lookup job, this endpoint returns the enriched details of all matching establishments, including validity status, establishment details, additional regulatory information, and recent EPF payment history.

This endpoint is designed to work in conjunction with the async initiation endpoint. Once a lookup is triggered, you use the returned client_id to query this status endpoint until the job reaches a terminal state (success or failed).

The response provides a comprehensive data payload for each matched establishment — covering PAN verification status, ownership type, business activity classification, EPFO office details, geographic metadata, and month-wise employee contribution data. This makes it highly useful for onboarding, compliance screening, and financial due diligence workflows.

Key Benefits

Comprehensive enrichment: A single API call returns validity status, establishment details, regulatory codes (CIN, ESIC, LIN), and recent payment history for each matching establishment.

Async-friendly polling: Built for high-volume workflows — the async pattern prevents timeout issues on large name-based lookups.

Historical payment insights: Month-wise EPF contribution data (employee count + amount) enables workforce trend analysis and financial health assessment.

Regulatory compliance ready: Surfacing PAN verification status, startup/MSME order details, and EPFO zone/region data simplifies compliance reporting.

Use Cases

Banking & Lending

HR & Staffing

Insurance & Fintech

Verify employer legitimacy and registration status when assessing salary account or loan applications linked to a company name.

Cross-check PAN verification status and EPFO registration of businesses applying for working capital or business loans.

Use month-wise employee count trends from payment details to assess workforce stability before extending credit.

Confirm ownership type (public/private) and business activity classification to meet KYB (Know Your Business) requirements.

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 <YOUR_JWT_TOKEN>.

Different JWT tokens are issued for sandbox and production environments:

Sandbox: https://sandbox.surepass.app

Production: https://kyc-api.surepass.app

⚠️ Never use a production JWT token against the sandbox environment, or vice versa. Tokens are environment-scoped.

Request Parameters

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer token — format: `Bearer <JWT_TOKEN>`. Use the JWT issued for the target environment (sandbox or production).
`Content-Type`	Yes	Must be `application/json`.

Request Body

Parameter	Type	Required	Description
`client_id`	string	Yes	The unique job identifier returned by the async initiation endpoint. Used to retrieve the result of the corresponding lookup job. Example: `establishment_name_to_details_async_client_id`

Example Request

{
    "client_id": "establishment_name_to_details_async_client_id"
}

Process Response

Response Parameters

Top-Level Fields

Parameter	Type	Description
`status_code`	integer	HTTP-equivalent status code for the operation (e.g., `200` for success).
`success`	boolean	`true` if the request was processed successfully; `false` otherwise.
`message`	string	Human-readable status message (e.g., `"Success"`).
`message_code`	string	Machine-readable message code (e.g., `"success"`).
`data`	object	Root data container. Present when `success` is `true`.

`data` Object

Parameter	Type	Description
`client_id`	string	Echo of the `client_id` submitted in the request, confirming which job this result belongs to.
`establishment_name`	string	The establishment name that was originally searched (as submitted in the async initiation request).
`hit_size`	integer	Total number of matching establishment records found for the given name.
`status`	string	Job status. Terminal values: `"success"` (results ready), `"failed"` (lookup failed). Non-terminal: `"processing"` (still running).
`details`	array	Array of matched establishment objects. Each element corresponds to one establishment record.

`details[]` — Each Establishment Object

validity_status Object

Parameter	Type	Description
`establishment_code`	string	Unique EPFO-assigned code for the establishment (e.g., `MHBAN1389044000`).
`establishment_name`	string	Official registered name of the establishment as per EPFO records.
`establishment_status`	string	Descriptive status of how the establishment code was allotted (e.g., post-online registration note).
`registration_status`	string	Current registration/login status on the ECR (Electronic Challan cum Return) portal.
`post_coverage`	string	Post coverage details, if any. May be empty.

establishment_details Object

Parameter	Type	Description
`establishment_name`	string	Official name of the establishment.
`establishment_code`	string	EPFO establishment code.
`pan_status`	string	PAN verification status (e.g., `"VERIFIED"`, `"NOT VERIFIED"`).
`section_applicable`	string	The EPF Act section under which the establishment is covered (e.g., 20+ employees, Central Govt notification).
`primary_business_activity`	string	Primary business activity category as classified by EPFO.
`esic_code`	string	Employee State Insurance Corporation (ESIC) code. May be empty if not applicable.
`ownership_type`	string	Legal ownership type (e.g., `"Public Ltd Company / Joint Stock Company"`).
`date_of_setup`	string (date)	Date the establishment was set up. Format: `YYYY-MM-DD`.
`address`	string	Registered office address.
`pincode`	string	PIN code of the establishment's registered address.
`city`	string	City of the registered address.
`district`	string	District of the registered address.
`state`	string	State of the registered address.
`country`	string	Country of the registered address.
`epfo_office_name`	string	Name of the EPFO regional/sub-regional office that administers this establishment.
`epfo_office_address`	string	Address of the administering EPFO office.
`zone`	string	EPFO zone under which the establishment falls (e.g., `"MAHARASHTRA AND CHHATTISGARH"`).
`region`	string	EPFO region code/name (e.g., `"MH - BANDRA"`).

additional_information Object

Parameter	Type	Description
`establishment_id`	string	Establishment identifier (same as `establishment_code`).
`cin_code`	string	Corporate Identification Number (CIN) as registered with MCA. May be empty for non-corporate entities.
`esic_code`	string	ESIC code. May be empty.
`lin_code`	string	Labour Identification Number (LIN). May be empty.
`startup_order_number`	string	Startup India order number, if the establishment is recognized as a startup. May be empty.
`startup_order_date`	string (date)	Date of startup recognition order. Format: `YYYY-MM-DD`. Placeholder value `1800-01-01` indicates not applicable.
`msme_order_number`	string	MSME registration order number. May be empty.
`msme_order_date`	string (date)	Date of MSME order. Format: `YYYY-MM-DD`. Placeholder value `1800-01-01` indicates not applicable.

payment_details[] Array — Each Payment Record

Parameter	Type	Description
`month`	string	Month and year of the EPF contribution (e.g., `"MAY-24"`).
`number_of_employees`	string	Number of employees for whom EPF contribution was filed that month. Returned as a string.
`amount`	string	Total EPF contribution amount (in INR paise or smallest unit) filed for that month. Returned as a string.

Example Successful Response

{
    "data": {
        "client_id": "establishment_name_to_details_async_qShvUrsPSmpdYmwckaPt",
        "establishment_name": "FIRST BANK LIMITED",
        "hit_size": 5,
        "status": "success",
        "details": [
            {
                "validity_status": {
                    "establishment_code": "MHBAN1389044000",
                    "establishment_name": "IDFC FIRST BANK LIMITED",
                    "establishment_status": "CODE NO ALLOTTED WAS AFTER ONLINE REGISTRATION STARTED.",
                    "registration_status": "PERMANENT LOGIN CREATED BY OWNER ON ECR PORTAL",
                    "post_coverage": ""
                },
                "establishment_details": {
                    "establishment_name": "IDFC FIRST BANK LIMITED",
                    "establishment_code": "MHBAN1389044000",
                    "pan_status": "VERIFIED",
                    "section_applicable": "OTHER ESTABLISHMENTS IN WHICH EMPLOYING 20 OR MORE PERSONS AND NOTIFIED BY THE CENTRAL GOVT.",
                    "primary_business_activity": "BANKS OTHER THAN NATIONALISED BANKS.",
                    "esic_code": "",
                    "ownership_type": "Public Ltd Company / Joint Stock Company",
                    "date_of_setup": "2014-10-21",
                    "address": "IDFC FIRST BANK TOWER THE SQUARE C 61 G BLOCK BANDRA KURLA COMPLEX ",
                    "pincode": "400051",
                    "city": "BANDRA EAST",
                    "district": "MUMBAI CITY",
                    "state": "MAHARASHTRA",
                    "country": "India",
                    "epfo_office_name": "BANDRA(MUMBAI-I)",
                    "epfo_office_address": "341, Bhavishya Nidhi Bhawan Bandra (East),",
                    "zone": "MAHARASHTRA AND CHHATTISGARH",
                    "region": "MH - BANDRA"
                },
                "additional_information": {
                    "establishment_id": "MHBAN1389044000",
                    "cin_code": "L65110TN2014PLC097792",
                    "esic_code": "",
                    "lin_code": "",
                    "startup_order_number": "",
                    "startup_order_date": "1800-01-01",
                    "msme_order_number": "",
                    "msme_order_date": "1800-01-01"
                },
                "payment_details": [
                    {
                        "month": "MAY-24",
                        "number_of_employees": "40774",
                        "amount": "258990897"
                    },
                    {
                        "month": "JUN-24",
                        "number_of_employees": "41390",
                        "amount": "260092921"
                    },
                    {
                        "month": "JUL-24",
                        "number_of_employees": "41165",
                        "amount": "260177104"
                    },
                    {
                        "month": "AUG-24",
                        "number_of_employees": "42108",
                        "amount": "264731780"
                    },
                    {
                        "month": "SEP-24",
                        "number_of_employees": "43103",
                        "amount": "268089509"
                    },
                    {
                        "month": "OCT-24",
                        "number_of_employees": "43345",
                        "amount": "271091459"
                    }
                ]
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid / Expired client_id

Unauthorized

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

Returned when the client_id does not correspond to any known async job, or the job record has expired. Verify that the client_id value matches exactly what was returned by the async initiation endpoint.

Integration Best Practices

Security Recommendations

Store JWT tokens securely: Never hardcode tokens in client-side code or commit them to version control. Use environment variables or a secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault).

Rotate tokens regularly: Treat JWT tokens as short-lived credentials. Implement automated token refresh before expiry to prevent service interruption.

Use HTTPS exclusively: Always call the API over HTTPS. Never downgrade to HTTP for sandbox testing.

Scope tokens per environment: Maintain strictly separate credentials for sandbox and production. Cross-environment token misuse will result in authentication failures and may cause unintended data exposure.

Validate client_id provenance: Store client_id values server-side (not in browser/client storage) and associate them with your internal job/session context to prevent IDOR-style misuse.

User Experience Guidelines

Implement exponential back-off polling: When status is "processing", retry with increasing intervals (e.g., 2s → 4s → 8s → 16s) up to a maximum wait threshold rather than polling at a fixed high frequency.

Handle multi-match results gracefully: Since hit_size can be greater than 1, design your UI to present a list of matching establishments and let users disambiguate using establishment_code, ownership_type, or address.

Treat empty string fields as not applicable: Fields like esic_code, lin_code, post_coverage and date placeholders (1800-01-01) indicate the data is not applicable for that establishment. Display user-friendly labels (e.g., "N/A") rather than raw empty strings or placeholder dates.

Surface payment trends visually: The payment_details array is month-ordered and ideal for rendering as a time-series chart of employee count or contribution amount — providing actionable insight at a glance.

Cache results appropriately: EPFO data does not change in real time. Once a job returns status: "success", cache the result for a reasonable TTL (e.g., 24 hours) to reduce redundant API calls.

Code Samples

cURL

Python

Node.js

Related APIs

EPFO Establishment Name to Details (Async — Initiate): Submits an establishment name for asynchronous lookup and returns a client_id to be used with this status endpoint.

EPFO Establishment Code to Details: Retrieves full establishment details using a known EPFO establishment code directly, without requiring name-based matching.

EPFO Member Passbook / UAN Lookup: Fetches individual employee-level EPF passbook or UAN details, complementing establishment-level data.

Company/Director Verification (MCA): Enriches establishment data with MCA-sourced director and company registration details, particularly useful when cin_code is present in the response.

GST Establishment Lookup: Cross-references EPFO establishment details with GST registration data for multi-source business verification.

Compliance and Legal Considerations

Data sourced from public EPFO registry: All data returned by this API is sourced from the publicly accessible EPFO employer portal. The information reflects the state of the EPFO registry at the time of lookup and may not capture real-time changes.

Purpose limitation: This API should be used strictly for lawful purposes such as KYB (Know Your Business) verification, employee onboarding, regulatory compliance checks, and credit risk assessment. Usage for surveillance, unsolicited outreach, or any purpose not aligned with applicable data protection laws is prohibited.

Data retention obligations: Consumers of this API must comply with applicable Indian data protection regulations, including the Digital Personal Data Protection Act (DPDPA), when storing or processing any personal or organizational data obtained through this endpoint.

Payment details are indicative: Monthly EPF contribution data is historical and publicly filed. It should not be construed as a real-time financial statement. For credit decisions, this data should be used as a supplementary signal alongside primary financial documents.

No guarantee of completeness: EPFO records may have gaps, delays, or inaccuracies originating from the source registry. Surepass does not warrant the completeness or absolute accuracy of the returned data. Always apply appropriate human review for high-stakes decisions.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Top-Level Fields#

data Object#

details[] — Each Establishment Object#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses