Company Details

Endpoint Overview

POST /api/v1/corporate/company-details

Description

This API retrieves comprehensive information about a company using its Corporate Identification Number (CIN). It provides detailed company data including registration information, financial details, management structure, and legal status. The endpoint returns structured data about the company's profile, its directors, and any charges registered against the company.

Key Benefits

Access complete company profile data from official registries in a single API call

Verify company legitimacy and operational status for due diligence processes

Obtain detailed information about company directors and financial obligations

Streamline KYC and compliance workflows with structured corporate data

Use Cases

Financial Services

Legal & Compliance

Business Intelligence

Perform corporate client onboarding with automated verification

Assess company creditworthiness based on registration details and financial status

Verify company legitimacy before establishing business relationships

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
id_number	String	Yes	Corporate Identification Number (CIN) of the company

Example Request

{
    "id_number": "U65999MH1995PLC123456"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the company information
data.client_id	String	Unique client identifier generated by the system
data.company_id	String	Company CIN number
data.company_type	String	Type of company
data.company_name	String	Registered name of the company
data.details	Object	Contains detailed company information
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Additional message (null if successful)
message_code	String	Code indicating the status of the request

Company Information Object (data.details.company_info)

Parameter	Type	Description
cin	String	Corporate Identification Number
roc_code	String	Registrar of Companies Code
registration_number	String	Registration Number
company_category	String	Category of the company
class_of_company	String	Class of the company (e.g., Public)
company_sub_category	String	Sub-category of the company
authorized_capital	String	Authorized capital of the company
paid_up_capital	String	Paid-up capital of the company
number_of_members	String	Number of members in the company
date_of_incorporation	String	Date of incorporation (YYYY-MM-DD)
registered_address	String	Registered address of the company
address_other_than_ro	String	Address other than Registrar of Companies
email_id	String	Email address of the company
listed_status	String	Listing status of the company
active_compliance	String	Active compliance status (if available)
suspended_at_stock_exchange	String	Status if suspended at stock exchange
last_agm_date	String	Date of the last Annual General Meeting (YYYY-MM-DD)
last_bs_date	String	Date of the last Balance Sheet (YYYY-MM-DD)
company_status	String	Status of the company (e.g., Active)
status_under_cirp	String	Status under Corporate Insolvency Resolution Process

Directors Object (data.details.directors)

Array of objects with the following structure:

Parameter	Type	Description
din_number	String	Director Identification Number (DIN)
director_name	String	Director's name
start_date	String	Start date of directorship (YYYY-MM-DD)
end_date	String	End date of directorship (YYYY-MM-DD)
surrendered_din	String	Surrendered Director Identification Number

Charges Object (data.details.charges)

Array of objects with the following structure:

Parameter	Type	Description
assets_under_charge	String	Description of assets under charge
charge_amount	String	Amount of the charge
date_of_creation	String	Date when the charge was created (YYYY-MM-DD)
date_of_modification	String	Date when the charge was modified (YYYY-MM-DD)
status	String	Status of the charge (OPEN/CLOSED)

Example Successful Response

{
    "data": {
        "client_id": "company_VxnpnqIgEtFTmTlDpucz",
        "company_id": "U65999MH1995PLC123456",
        "company_type": "Company",
        "company_name": "FINSERV LIMITED",
        "details": {
            "company_info": {
                "cin": "U65999MH1995PLC123456",
                "roc_code": "Mumbai",
                "registration_number": "123456",
                "company_category": "Company limited by Shares",
                "class_of_company": "Public",
                "company_sub_category": "Non-govt company",
                "authorized_capital": "1750000000",
                "paid_up_capital": "1500000000",
                "number_of_members": "0",
                "date_of_incorporation": "1995-03-14",
                "registered_address": "J.B. Nagar Metro Station, J.B. Nagar, Andheri (E) Mumbai Mumbai City MH 400059 IN",
                "address_other_than_ro": "-",
                "email_id": "nikita.@FINSERV.com",
                "listed_status": "Unlisted",
                "active_compliance": null,
                "suspended_at_stock_exchange": "-",
                "last_agm_date": "2023-09-06",
                "last_bs_date": "2023-03-31",
                "company_status": "Active",
                "status_under_cirp": null
            },
            "directors": [
                {
                    "din_number": "123456",
                    "director_name": "AMIT GOYAL",
                    "start_date": "2014-08-04",
                    "end_date": "1800-01-01",
                    "surrendered_din": null
                },
                {
                    "din_number": "456789",
                    "director_name": "CHANDRASHEKHAR GURUSWAMY AIYAR",
                    "start_date": "2016-03-30",
                    "end_date": "1800-01-01",
                    "surrendered_din": null
                },
                {
                    "din_number": "987456",
                    "director_name": "AMIT KHANDELWAL",
                    "start_date": "2014-08-04",
                    "end_date": "1800-01-01",
                    "surrendered_din": null
                },
                {
                    "din_number": "654321",
                    "director_name": "AMITH AGARWAL",
                    "start_date": "2014-08-04",
                    "end_date": "1800-01-01",
                    "surrendered_din": null
                }
            ],
            "charges": [
                {
                    "assets_under_charge": " Book debts",
                    "charge_amount": "150000000",
                    "date_of_creation": "2015-10-20",
                    "date_of_modification": "1800-01-01",
                    "status": "CLOSED"
                },
                {
                    "assets_under_charge": " Book debts",
                    "charge_amount": "140000000",
                    "date_of_creation": "2015-12-15",
                    "date_of_modification": "1800-01-01",
                    "status": "CLOSED"
                },
                {
                    "assets_under_charge": " Book debts",
                    "charge_amount": "500000000",
                    "date_of_creation": "2015-11-04",
                    "date_of_modification": "1800-01-01",
                    "status": "CLOSED"
                },
                {
                    "assets_under_charge": " Book debts",
                    "charge_amount": "50000000",
                    "date_of_creation": "2015-08-31",
                    "date_of_modification": "1800-01-01",
                    "status": "CLOSED"
                },
                {
                    "assets_under_charge": " Book debts; Standard asset portfolio",
                    "charge_amount": "50000000",
                    "date_of_creation": "2016-08-30",
                    "date_of_modification": "1800-01-01",
                    "status": "OPEN"
                },
                {
                    "assets_under_charge": " Book debts",
                    "charge_amount": "100000000",
                    "date_of_creation": "2016-07-29",
                    "date_of_modification": "1800-01-01",
                    "status": "CLOSED"
                },
                {
                    "assets_under_charge": " Book debts; Loan Assets, Receivables",
                    "charge_amount": "250000000",
                    "date_of_creation": "2016-08-22",
                    "date_of_modification": "1800-01-01",
                    "status": "OPEN"
                },
                {
                    "assets_under_charge": " Book debts; Standard asset portfolio",
                    "charge_amount": "150000000",
                    "date_of_creation": "2016-08-30",
                    "date_of_modification": "1800-01-01",
                    "status": "OPEN"
                },
                {
                    "assets_under_charge": " Book debts; Receivables",
                    "charge_amount": "100000000",
                    "date_of_creation": "2016-09-28",
                    "date_of_modification": "1800-01-01",
                    "status": "CLOSED"
                },
                {
                    "assets_under_charge": " Book debts; Receivables(Present & Future) /Corporate Guarantee",
                    "charge_amount": "250000000",
                    "date_of_creation": "2016-12-29",
                    "date_of_modification": "1800-01-01",
                    "status": "OPEN"
                }
            ]
        }
    },
    "status_code": 200,
    "success": true,
    "message": null,
    "message_code": "success"
}

Possible Error Responses

Invalid CIN

Authentication Error

Company Not Found

{
    "data": null,
    "status_code": 400,
    "success": false,
    "message": "Invalid CIN format",
    "message_code": "invalid_input"
}

The provided Corporate Identification Number is invalid or in an incorrect format.

Integration Best Practices

Security Recommendations

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

Implement proper error handling to avoid exposing sensitive information

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

Rotate JWT tokens periodically and implement token expiration policies

Implement IP whitelisting for production environments if supported

User Experience Guidelines

Cache company information when appropriate to reduce API calls and improve response times

Implement progressive loading for displaying large company data responses

Format financial figures (capital amounts) with appropriate currency symbols and separators

Display dates in a user-friendly format while maintaining ISO format (YYYY-MM-DD) in requests

Provide clear error messages to end-users when company information cannot be retrieved

Code Samples

cURL

Python

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/corporate/company-details' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "id_number": "U65999MH1995PLC123456" }'

{ "data": { "client_id": "company_VxnpnqIgEtFTmTlDpucz", "company_id": "U65999MH1995PLC123456", "company_type": "Company", "company_name": "FINSERV LIMITED", "details": { "company_info": { "cin": "U65999MH1995PLC123456", "roc_code": "Mumbai", "registration_number": "123456", "company_category": "Company limited by Shares", "class_of_company": "Public", "company_sub_category": "Non-govt company", "authorized_capital": "1750000000", "paid_up_capital": "1500000000", "number_of_members": "0", "date_of_incorporation": "1995-03-14", "registered_address": "J.B. Nagar Metro Station, J.B. Nagar, Andheri (E) Mumbai Mumbai City MH 400059 IN", "address_other_than_ro": "-", "email_id": "nikita.@FINSERV.com", "listed_status": "Unlisted", "active_compliance": null, "suspended_at_stock_exchange": "-", "last_agm_date": "2023-09-06", "last_bs_date": "2023-03-31", "company_status": "Active", "status_under_cirp": null }, "directors": [ { "din_number": "123456", "director_name": "AMIT GOYAL", "start_date": "2014-08-04", "end_date": "1800-01-01", "surrendered_din": null }, { "din_number": "456789", "director_name": "CHANDRASHEKHAR GURUSWAMY AIYAR", "start_date": "2016-03-30", "end_date": "1800-01-01", "surrendered_din": null }, { "din_number": "987456", "director_name": "AMIT KHANDELWAL", "start_date": "2014-08-04", "end_date": "1800-01-01", "surrendered_din": null }, { "din_number": "654321", "director_name": "AMITH AGARWAL", "start_date": "2014-08-04", "end_date": "1800-01-01", "surrendered_din": null } ], "charges": [ { "assets_under_charge": " Book debts", "charge_amount": "150000000", "date_of_creation": "2015-10-20", "date_of_modification": "1800-01-01", "status": "CLOSED" }, { "assets_under_charge": " Book debts", "charge_amount": "140000000", "date_of_creation": "2015-12-15", "date_of_modification": "1800-01-01", "status": "CLOSED" }, { "assets_under_charge": " Book debts", "charge_amount": "500000000", "date_of_creation": "2015-11-04", "date_of_modification": "1800-01-01", "status": "CLOSED" }, { "assets_under_charge": " Book debts", "charge_amount": "50000000", "date_of_creation": "2015-08-31", "date_of_modification": "1800-01-01", "status": "CLOSED" }, { "assets_under_charge": " Book debts; Standard asset portfolio", "charge_amount": "50000000", "date_of_creation": "2016-08-30", "date_of_modification": "1800-01-01", "status": "OPEN" }, { "assets_under_charge": " Book debts", "charge_amount": "100000000", "date_of_creation": "2016-07-29", "date_of_modification": "1800-01-01", "status": "CLOSED" }, { "assets_under_charge": " Book debts; Loan Assets, Receivables", "charge_amount": "250000000", "date_of_creation": "2016-08-22", "date_of_modification": "1800-01-01", "status": "OPEN" }, { "assets_under_charge": " Book debts; Standard asset portfolio", "charge_amount": "150000000", "date_of_creation": "2016-08-30", "date_of_modification": "1800-01-01", "status": "OPEN" }, { "assets_under_charge": " Book debts; Receivables", "charge_amount": "100000000", "date_of_creation": "2016-09-28", "date_of_modification": "1800-01-01", "status": "CLOSED" }, { "assets_under_charge": " Book debts; Receivables(Present & Future) /Corporate Guarantee", "charge_amount": "250000000", "date_of_creation": "2016-12-29", "date_of_modification": "1800-01-01", "status": "OPEN" } ] } }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

Company Details

Company Details#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Company Information Object (data.details.company_info)#

Directors Object (data.details.directors)#

Charges Object (data.details.charges)#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Company Details

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Company Information Object (data.details.company_info)

Directors Object (data.details.directors)

Charges Object (data.details.charges)

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples