Submit Request without Webhook

Endpoint Overview

POST /api/v1/async/submit

Description

This API endpoint allows you to submit asynchronous verification requests without requiring a webhook callback. It's designed for Aadhaar validation and other identity verification processes where you need to initiate a verification task and check its status later. This approach is ideal for systems that prefer polling for results rather than receiving webhook notifications.

Key Benefits

Initiate verification processes without setting up webhook infrastructure

Receive a unique client ID to track the status of your request

Compatible with various identity verification types including Aadhaar validation

Simplified integration for systems that prefer polling over push notifications

Use Cases

Financial Services

Government Services

Healthcare

Customer onboarding for banking and financial applications

KYC verification for loan processing systems

Identity verification for digital wallet registrations

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 authentication using JWT format: `Bearer <your_jwt_token>`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
type	String	Yes	The type of verification to perform (e.g., "aadhaar_validation")
body	Object	Yes	Contains the verification-specific parameters
body.id_number	String	Yes	The Aadhaar number to validate when type is "aadhaar_validation"

Example Request

{
    "type": "aadhaar_validation",
    "body": {
        "id_number": "{{aadhaar_number}}"
    }
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the response data
data.client_id	String	Unique identifier for tracking this verification request
data.status	String	Current status of the request (e.g., "pending")
data.api_resp	Object/null	API response data (null when status is pending)
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successfully submitted
message	String	Human-readable status message
message_code	String	Machine-readable status code

Example Successful Response

{
    "data": {
        "client_id": "aadhaar_validation_asfdshSJnOkrzMD",
        "status": "pending",
        "api_resp": null
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Validation Error

{
    "status_code": 401,
    "success": false,
    "message": "Invalid authentication token",
    "message_code": "authentication_error"
}

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

Integration Best Practices

Security Recommendations

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

Implement proper error handling to avoid exposing sensitive information

Validate all input data before sending to the API

Use HTTPS for all API communications

User Experience Guidelines

Implement a polling mechanism to check the status of pending requests

Display appropriate loading indicators during verification

Provide clear error messages to end-users when verification fails

Consider implementing a retry mechanism for failed verifications

Code Samples

cURL

Python

Node.js

Related APIs

Check Async Status: Retrieve the status and results of a previously submitted async request

Aadhaar OCR: Extract information from Aadhaar card images

PAN Validation: Validate PAN card details

Face Match: Compare facial biometrics for identity verification

Compliance and Legal Considerations

When handling Aadhaar data, ensure compliance with the Aadhaar Act, 2016 and UIDAI regulations. Store and process Aadhaar numbers in accordance with applicable privacy laws and data protection standards. Obtain appropriate user consent before initiating verification processes.

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/async/submit' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "type": "aadhaar_validation", "body": { "id_number": "{{aadhaar_number}}" } }'

{ "data": { "client_id": "aadhaar_validation_asfdshSJnOkrzMD", "status": "pending", "api_resp": null }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Submit Request without Webhook

Submit Request without Webhook#

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

Submit Request without Webhook

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples