Create Order

Endpoint Overview

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

Description

This API initiates a new order to retrieve the Ultimate Beneficial Owner (UBO) information for a business entity. It creates a tracking request in the system and returns a unique client ID that can be used to monitor the status of the UBO information retrieval process. The API accepts various entity identification formats and provides immediate status information about the entity.

Key Benefits

Quickly initiate UBO verification for regulatory compliance

Support for multiple entity identification formats (CIN, PAN, LLP)

Real-time status tracking of verification requests

Seamless integration with MCA (Ministry of Corporate Affairs) database

Use Cases

Financial Services

Corporate Compliance

Legal Services

KYC verification for corporate banking clients

Due diligence for business loan applications

Regulatory compliance for financial institutions

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
entity_id	String	Yes	Unique identifier for the entity. Accepts CIN, PAN, or LLP formats.

Example Request

{
    "entity_id": "NHQPS9361L"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the response data
data.client_id	String	Unique identifier for the API request
data.entity_id	String	Entity's unique identification number
data.entity_type	String	Type of the entity (e.g., company)
data.status	String	Current status of the entity (pending, completed, or failed)
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Human-readable message about the response
message_code	String	Machine-readable message code

Example Successful Response

{
    "data": {
        "client_id": "mca_ubo_BQgmfkfdFjxqhwRedZyv",
        "entity_id": "L51500MH9876PLC001234",
        "entity_type": "company",
        "status": "pending"
    },
    "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 is not in a valid CIN, PAN, or LLP format.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement token refresh mechanisms to handle token expiration

Use HTTPS for all API communications to ensure data encryption

Implement proper error handling for authentication failures

User Experience Guidelines

Provide clear feedback to users about the status of their verification request

Implement a polling mechanism to check for status updates

Display appropriate waiting messages for pending verifications

Handle and display error messages in a user-friendly manner

Code Samples

cURL

Python

Node.js

Related APIs

Check Order Status: Retrieves the current status of a previously created UBO verification order

Get UBO Details: Fetches the complete UBO information for a completed verification

Entity Search: Searches for entities by name or partial identification

Compliance and Legal Considerations

The UBO information retrieved through this API is sourced from official government records and should be used in compliance with applicable data protection and privacy regulations. The information should only be used for legitimate business purposes such as KYC verification, regulatory compliance, or due diligence. Unauthorized use or distribution of this information may violate privacy laws.

{ "data": { "client_id": "mca_ubo_BQgmfkfdFjxqhwRedZyv", "entity_id": "L51500MH9876PLC001234", "entity_type": "company", "status": "pending" }, "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 ********************

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