Create Order

Endpoint Overview

POST /api/v1/mca-api/create-order

Description

This API endpoint initiates a new MCA (Ministry of Corporate Affairs) data retrieval order for a specified entity. It allows you to request company information from the MCA database by providing the entity's registration ID. Upon successful creation, the API returns a client ID that can be used to track and reference this order in subsequent API calls.

Key Benefits

Streamlined access to official company registration data from MCA

Automated verification of company existence and registration details

Simplified KYC and due diligence processes for business entities

Reduced manual effort in company information retrieval

Use Cases

Financial Services

B2B Services

Legal & Compliance

Verify company existence and registration details before approving business loans

Conduct due diligence on potential corporate clients during onboarding

Validate company information for credit risk assessment

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

Request Body

Parameter	Type	Required	Description
entity_id	String	Yes	The CIN (Corporate Identity Number) or registration ID of the company. Format should match the standard MCA registration format (e.g., U72900MH2017PTC294100)

Example Request

{
    "entity_id": "U72900MH2017PTC294100"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the order details
data.client_id	String	Unique identifier for the created order, used in subsequent API calls
data.entity_id	String	The CIN or registration ID that was provided in the request
data.entity_type	String	Type of entity for which the order was created (e.g., "company")
data.fetch_only	Boolean	Was the order in fetch only mode
status_code	Integer	HTTP status code indicating the result of the request
success	Boolean	Indicates whether the API call was successful
message	String	Human-readable description of the result
message_code	String	Machine-readable code representing the result

Example Successful Response

{
    "data": {
        "client_id": "mca_ampKghRzCzyrLnamvfSn",
        "entity_id": "U72900MH2017PTC294100",
        "entity_type": "company",
        "fetch_only": false
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Entity ID

Authentication Error

{
    "status_code": 400,
    "success": false,
    "message": "Invalid entity ID format",
    "message_code": "invalid_entity_id"
}

The provided entity_id does not match the expected format for a valid MCA registration number.

Integration Best Practices

Security Recommendations

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

Implement proper error handling to avoid exposing sensitive information

Rotate JWT tokens periodically and implement token expiration policies

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

User Experience Guidelines

Implement proper loading states while waiting for API responses

Provide clear error messages to users when entity verification fails

Cache successful responses when appropriate to improve performance

Implement retry logic with exponential backoff for failed requests

Code Samples

cURL

Python

Node.js

Related APIs

Get Order Status: Check the status of a previously created MCA order

Get Company Details: Retrieve detailed company information after order processing

Get Company Directors: Fetch information about company directors and key personnel

Get Company Charges: Obtain information about charges registered against the company

Compliance and Legal Considerations

The data retrieved through this API is sourced from the Ministry of Corporate Affairs (MCA) and is subject to MCA terms of use. This data should be used in compliance with applicable data protection laws and regulations. The information should not be used for unsolicited communication or marketing purposes without proper consent.

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/mca-api/create-order' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "entity_id": "U72900MH2017PTC294100" }'

{ "data": { "client_id": "mca_ampKghRzCzyrLnamvfSn", "entity_id": "U72900MH2017PTC294100", "entity_type": "company" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Create Order

Create Order#

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

Create Order

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples