Order List

Endpoint Overview

GET /api/v1/mca-api/order-list

Description

This API endpoint retrieves a list of Ministry of Corporate Affairs (MCA) verification orders associated with your account. It provides status information about company verification requests, including pending orders, successful verifications, and any errors encountered during the verification process. This endpoint is essential for tracking the progress of company verification requests and managing your verification workflow.

Key Benefits

Track the status of multiple company verification requests in a single API call

Quickly identify failed verifications and their specific error reasons

Monitor pending verifications that require additional credentials or payment

Efficiently manage verification workflows with comprehensive status tracking

Use Cases

Financial Services

Business Services

Compliance

Retrieve status of company verification requests during customer onboarding

Track pending verifications requiring additional documentation

Monitor verification failures for compliance reporting

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

This endpoint does not require a request body as it's a GET request to retrieve order information.

Process Response

Response Parameters

Parameter	Type	Value
data	Array	List of order objects details
data.entity_name	String	TECH SOLUTIONS PRIVATE LIMITED
data.credentials_provided	Boolean	false
data.status	String	completed
data.mca_srn	Null	null
data.error	Null	null
data.error_description	Null	null
data.mca_payment	Boolean	true
data.fetch_only	Null	null
data.payment_reversal	Boolean	false
data.auto_reversal	Boolean	false
data.total_documents	Integer	3
data.completed_documents	Integer	1
status_code	Integer	200
success	Boolean	true
message	String	Success
message_code	String	success

Example Successful Response

{
  "data": {
    "entity_name": "TECH SOLUTIONS PRIVATE LIMITED",
    "credentials_provided": false,
    "status": "completed",
    "mca_srn": null,
    "error": null,
    "error_description": null,
    "mca_payment": true,
    "fetch_only": null,
    "payment_reversal": false,
    "auto_reversal": false,
    "total_documents": 3,
    "completed_documents": 1
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Possible Error Responses

Authentication Error

Server Error

{
    "data": null,
    "status_code": 401,
    "success": false,
    "message": "Invalid or expired token",
    "message_code": "authentication_error"
}

This error occurs when the provided JWT token is invalid, expired, or missing.

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

Poll this endpoint at reasonable intervals to track verification status changes

Implement clear status indicators in your UI based on the verification status

Provide users with specific guidance when additional credentials are required

Display helpful error messages when verification fails

Code Samples

cURL

Python

Node.js

Related APIs

MCA Company Verification API - Initiates verification of a company using MCA records

MCA Verification Status API - Checks the status of a specific verification request

MCA Document Retrieval API - Retrieves documents associated with verified companies

Compliance and Legal Considerations

The data retrieved through this API may contain sensitive company information protected under various privacy laws. Ensure you have proper consent and legal basis for processing this information. The use of MCA data is subject to Ministry of Corporate Affairs regulations and should be used in compliance with applicable laws.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": { "entity_name": "TECH SOLUTIONS PRIVATE LIMITED", "credentials_provided": false, "status": "completed", "mca_srn": null, "error": null, "error_description": null, "mca_payment": true, "fetch_only": null, "payment_reversal": false, "auto_reversal": false, "total_documents": 3, "completed_documents": 1 }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Order List

Order List#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Order List

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples