Establishment Name Details

Endpoint Overview

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

Description

This API retrieves comprehensive information about an establishment based on its name. It provides detailed data including validity status, establishment details, additional information, and payment history from EPFO (Employees' Provident Fund Organisation) records. The API helps verify the existence and current status of an establishment, along with its compliance history with EPFO regulations.

Key Benefits

Verify establishment existence and registration status with EPFO

Access comprehensive establishment details including address, business activity, and ownership type

Retrieve payment history to assess compliance with EPFO contributions

Validate establishment credentials for due diligence and compliance checks

Use Cases

Financial Services

HR & Payroll

Business Verification

Verify business credentials during loan application processing

Assess establishment compliance history for credit risk evaluation

Validate establishment details for KYB (Know Your Business) processes

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

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

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication (JWT format)
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
establishment_name	String	Yes	Name of the establishment to retrieve details for
hit_size	Integer	No	Hit size limit

Example Request

{
    "establishment_name": "FIRST BANK LIMITED"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the establishment information
data.client_id	String	Unique identifier for the API request
data.establishment_name	String	Full name of the establishment
data.details	Object	Contains detailed information about the establishment
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Response message
message_code	String	Code indicating the response status

Details Object Structure

Parameter	Type	Description
validity_status	Object	Contains information about the establishment's validity
establishment_details	Object	Contains comprehensive details about the establishment
additional_information	Object	Contains supplementary information about the establishment
payment_details	Array	Contains payment history records

Example Successful Response

{
    "data": {
        "client_id": "establishment_name_to_details_dQwgnYieEOqyflHOiPRn",
        "establishment_name": "IDFC FIRST BANK LIMITED",
        "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

Establishment Not Found

Authentication Error

Validation Error

{
    "status_code": 404,
    "success": false,
    "message": "Establishment not found",
    "message_code": "establishment_not_found"
}

This error occurs when the provided establishment name does not match any records in the EPFO database.

Integration Best Practices

Security Recommendations

Store API credentials securely and never expose them in client-side code

Implement proper error handling to prevent sensitive information leakage

Use HTTPS for all API communications to ensure data encryption in transit

Implement token refresh mechanisms to handle token expiration gracefully

User Experience Guidelines

Implement fuzzy matching to handle slight variations in establishment names

Display comprehensive establishment details in an organized, easy-to-read format

Provide clear error messages to users when establishment information cannot be found

Implement caching strategies to improve response times for frequently queried establishments

Code Samples

cURL

Python

Node.js

Related APIs

EPFO Establishment Code to Details API: Retrieves establishment details using the establishment code

EPFO Establishment Verification API: Verifies the existence and status of an establishment

EPFO Payment History API: Retrieves detailed payment history for an establishment

Compliance and Legal Considerations

The data provided by this API is sourced from EPFO records and should be used in compliance with applicable data protection laws. The information should only be used for legitimate business purposes such as verification, due diligence, and compliance checks. Unauthorized use or distribution of this data may violate privacy regulations and terms of service.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/epfo/establishment-name-to-details' \ --header 'Content-Type: application/json' \ --data-raw '{ "establishment_name": "FIRST BANK LIMITED" }'

{ "data": { "client_id": "establishment_name_to_details_dQwgnYieEOqyflHOiPRn", "establishment_name": "IDFC FIRST BANK LIMITED", "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" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Establishment Name Details

Establishment Name Details#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Details Object Structure#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Establishment Name Details

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Details Object Structure

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples