Submit Request

Endpoint Overview

POST /api/v1/async/submit

Description

The Async Submit API endpoint allows you to initiate asynchronous verification processes, such as Aadhaar validation, without waiting for the completion of the verification. This endpoint accepts the verification request, returns a client ID immediately, and then sends the complete verification results to your specified webhook URL once processing is complete. This approach is ideal for verification processes that may take time to complete, allowing your application to continue functioning without blocking user interactions.

Key Benefits

Non-blocking operations: Continue your application flow while verification happens in the background

Webhook notifications: Receive results automatically when processing completes

Flexible integration: Support for multiple verification types through a single endpoint

Reliable tracking: Each request receives a unique client ID for status tracking

Use Cases

Financial Services

Healthcare

E-commerce

Asynchronous KYC verification during customer onboarding

Background identity checks for loan applications

Periodic customer verification updates without disrupting user experience

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_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 ID number to verify (e.g., Aadhaar number)
webhook_url	String	Yes	The URL where verification results will be sent upon completion

Example Request

{
    "type": "aadhaar_validation",
    "body": {
        "id_number": "123456789012"
    },
    "webhook_url": "https://your-domain.com/webhook/callback"
}

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 verification (e.g., "pending")
data.api_resp	Object/null	API response data (null for pending requests)
status_code	Integer	HTTP status code
success	Boolean	Indicates if the request was successfully received
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

{
    "data": null,
    "status_code": 401,
    "success": false,
    "message": "Invalid authentication token",
    "message_code": "auth_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 IP whitelisting for your webhook endpoints to prevent unauthorized callbacks

Validate the webhook payload to ensure it comes from Surepass

Use HTTPS for all webhook URLs to ensure data is encrypted in transit

User Experience Guidelines

Inform users that verification is in progress after submission

Implement a status page where users can check verification progress

Set up proper error handling to gracefully manage verification failures

Consider implementing a retry mechanism for failed verifications

Code Samples

cURL

Python

Node.js

Related APIs

Async Status Check API: Check the status of an asynchronous verification request

Webhook Configuration API: Configure default webhook URLs for your account

Verification History API: Retrieve historical verification results

Compliance and Legal Considerations

When handling Aadhaar or other personal identification information, ensure compliance with relevant data protection regulations such as the Aadhaar Act, IT Act, and other applicable privacy laws. Store verification data securely and only for the duration necessary for your business purposes. Obtain proper consent from users before initiating verification processes.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/async/submit' \ --header 'Content-Type: application/json' \ --data-raw '{ "type": "aadhaar_validation", "body": { "id_number": "{{aadhaar_number}}" }, "webhook_url": "{{webhook_url}}" }'

{ "data": { "client_id": "aadhaar_validation_asfdshSJnOkrzMD", "status": "pending", "api_resp": null }, "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 ********************

Submit Request

Submit Request#

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

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples