Get Async Status

Endpoint Overview

GET /api/v1/async/status/{client_id}

Description

This endpoint allows you to check the status and retrieve results of an asynchronous operation that was previously initiated. It provides a way to poll for the completion status of long-running operations using the unique client ID that was assigned when the operation was started.

Key Benefits

Enables non-blocking architecture for time-consuming operations

Provides detailed status tracking for asynchronous processes

Returns complete operation results when processing is complete

Allows efficient resource utilization for long-running tasks

Use Cases

Financial Services

Government Services

Healthcare

Track status of KYC verification processes

Monitor document verification workflows

Poll for completion of identity verification checks

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. Format: `Bearer {your_jwt_token}`
Content-Type	Yes	Must be set to `application/json`

Path Parameters

Parameter	Type	Required	Description
client_id	String	Yes	The unique identifier for the asynchronous operation you want to check. This ID was provided when the operation was initiated.

This endpoint does not require a request body.

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the response data
data.client_id	String	The unique identifier for the asynchronous operation
data.status	String	Current status of the operation (e.g., "success", "pending", "failed")
data.api_resp	Object	The complete response from the original API call once processing is complete
data.api_resp.data	Object	Contains the actual data returned by the completed operation
data.api_resp.data.client_id	String	Client ID of the original operation
data.api_resp.data.age_range	String	Age range of the verified individual
data.api_resp.data.aadhaar_number	String	Aadhaar number that was validated
data.api_resp.data.state	String	State of residence according to Aadhaar
data.api_resp.data.gender	String	Gender code (M/F/O)
data.api_resp.data.last_digits	String	Last digits of the Aadhaar number
data.api_resp.data.is_mobile	Boolean	Indicates if a mobile number is linked to the Aadhaar
data.api_resp.data.less_info	Boolean	Indicates if limited information was returned
data.api_resp.status_code	Integer	HTTP status code of the original operation
data.api_resp.success	Boolean	Whether the original operation was successful
data.api_resp.message	String or null	Additional message about the operation
data.api_resp.message_code	String	Code indicating the result of the operation
status_code	Integer	HTTP status code of this status check request
success	Boolean	Whether this status check request was successful
message	String	Human-readable message about this status check
message_code	String	Code indicating the result of this status check

Example Successful Response

{
    "data": {
        "client_id": "async_zyHraBgkBKOyyYciilNx",
        "status": "success",
        "api_resp": {
            "data": {
                "client_id": "aadhaar_validation_asfdshSJnOkrzMD",
                "age_range": "20-30",
                "aadhaar_number": "123456789010",
                "state": "Delhi",
                "gender": "M",
                "last_digits": "123",
                "is_mobile": true,
                "less_info": false
            },
            "status_code": 200,
            "success": true,
            "message": null,
            "message_code": "success"
        }
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Not Found

Pending

Authentication Error

{
    "status_code": 404,
    "success": false,
    "message": "Client ID not found",
    "message_code": "client_id_not_found"
}

This error occurs when the provided client_id does not exist or has expired.

Integration Best Practices

Security Recommendations

Store client_ids securely as they can be used to retrieve sensitive information

Implement proper error handling for failed status checks

Use HTTPS for all API communications to ensure data security

Implement token refresh mechanisms to handle JWT expiration

User Experience Guidelines

Implement exponential backoff for polling to reduce server load

Display appropriate progress indicators to users during async operations

Cache results once received to avoid unnecessary API calls

Set reasonable timeouts for long-running operations

Code Samples

cURL

Python

Node.js

Related APIs

Initiate Async Aadhaar Validation - Starts an asynchronous Aadhaar validation process

Initiate Async Document Verification - Begins an asynchronous document verification process

Initiate Async Face Match - Starts an asynchronous face matching operation

Compliance and Legal Considerations

When handling Aadhaar data, ensure compliance with the Aadhaar Act, 2016 and UIDAI regulations. Store and process data in accordance with the Information Technology Act, 2000 and relevant data protection laws. Implement appropriate consent mechanisms before initiating verification processes.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": { "client_id": "async_zyHraBgkBKOyyYciilNx", "status": "success", "api_resp": { "data": { "client_id": "aadhaar_validation_asfdshSJnOkrzMD", "age_range": "20-30", "aadhaar_number": "123456789010", "state": "Delhi", "gender": "M", "last_digits": "123", "is_mobile": true, "less_info": false }, "status_code": 200, "success": true, "message": null, "message_code": "success" } }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Get Status

Get Async Status#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Path Parameters#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses