Overview

The Surepass connector enables your AI Colleagues to integrate with Surepass, a digital identity verification platform, to automate KYC verification, Aadhaar and bank account checks, and Aadhaar-based e-signature workflows.

Surepass provides APIs for identity verification, bank account validation, and legally valid electronic signatures in India. The Surepass connector allows Leena AI to verify employee identities during onboarding, validate bank details for payroll, and send documents for Aadhaar e-sign, then track and retrieve the signed documents.

API Details

Leena AI integrates with Surepass via its REST APIs.

• Base URL: https://kyc-api.surepass.io
• Authentication: Bearer token (Authorization: Bearer <API token>)

Documentation link: https://surepass.io

Setup

The Surepass connector supports one authentication method:

• SurePass bearer auth: Authenticates every request with your Surepass API token

Prerequisites

Before setting up the Surepass connector, ensure you have:

• A Surepass account with API access
• A valid API token from the Surepass dashboard
• The Surepass services you plan to use activated on your account (Aadhaar verification, bank verification, e-sign)
• Access to your Leena AI workspace with connector management permissions
• Compliance with applicable Indian regulations: the Aadhaar Act and UIDAI guidelines (Aadhaar actions), RBI guidelines (bank verification), IT Act provisions (e-signatures), and Indian data protection laws

Get credentials

Here is how to get your API token from Surepass:

1. Log in to your Surepass account at https://surepass.io
2. Open the API Settings / Developer section of the dashboard
3. Generate (or copy) your API token
4. Store the token securely; it grants access to all Surepass services enabled on your account

If you don't have API access yet, request it through Surepass's API access form at https://surepass.io/get-api-key/.

Add connection

Here is how to add a connection on Leena AI:

1. Log in to your Leena AI workspace
2. Navigate to Settings > Integrations
3. Search for "Surepass" and select it from the list to add its new connector
4. Configure the connector:
   1. Auth type: Select "SurePass bearer auth"
   2. API token: Your Surepass API token (stored as a secret and masked after saving)
5. Save the connector configuration

Actions

The following actions are supported for the Surepass connector:

Generate Aadhaar OTP

Sends an OTP to the mobile number linked to an Aadhaar number. This is the first step of OTP-based Aadhaar verification; the returned Client ID is used in Submit Aadhaar OTP.

Input Parameters

Mandatory

Here is a sample JSON input:

{
  "id_number": "123456789012"
}

Response

• Client ID (used to submit the OTP)
• OTP sent status
• Message

Submit Aadhaar OTP

Submits the OTP received by the Aadhaar holder to complete verification and returns the demographic details from Aadhaar.

Input Parameters

Mandatory

Here is a sample JSON input:

{
  "client_id": "aadhaar_v2_xxxxxxxxxxxxxxxx",
  "otp": "123456"
}

Response

• Full name
• Date of birth
• Gender
• Address details
• Photo (base64)
• Verification status

Aadhaar Validation

Validates an Aadhaar number without an OTP. Use this for a quick check that an Aadhaar number exists and is active.

Input Parameters

Mandatory

Here is a sample JSON input:

{
  "id_number": "123456789012"
}

Response

• Aadhaar validity status
• Age range
• Gender
• State of residence
• Mobile number availability status

Bank Account Verification

Verifies a bank account using a penny drop: a small IMPS transaction is made to confirm that the account exists and to fetch the account holder's name.

Input Parameters

Mandatory

Optional

Here is a sample JSON input:

{
  "id_number": "1234567890",
  "ifsc": "HDFC0001234",
  "ifsc_details": true
}

Response

• Account holder name
• Account existence status
• Bank and branch details (if ifsc_details is true)
• IMPS reference number
• Transaction status

Bank Account Verification (Pennyless)

Verifies a bank account instantly without a monetary transaction.

Input Parameters

Mandatory

Optional

Here is a sample JSON input:

{
  "id_number": "1234567890",
  "ifsc": "HDFC0001234",
  "ifsc_details": true
}

Response

• Account holder name
• Account validity status
• Bank and branch details (if ifsc_details is true)
• Verification timestamp

Initialize E-Sign

Creates an e-sign request in Surepass and returns a signing link for the signer. The Agent can leverage this tool to send offer letters, agreements, or onboarding documents for Aadhaar-based e-signature.

Input Parameters

Mandatory

Optional

NSDL and NSDL with stamp only (all default to true):

NSDL with stamp only:

Here is a sample JSON input (NSDL):

{
  "sign_type": "nsdl",
  "pdf_pre_uploaded": true,
  "pdf_url": "https://example.com/documents/offer_letter.pdf",
  "callbackSource": "ONBOARDING",
  "config": {
    "reason": "Offer letter acceptance",
    "skip_otp": false,
    "accept_selfie": true,
    "allow_selfie_upload": true,
    "accept_virtual_sign": true,
    "track_location": true
  },
  "positions": [
    { "page": 1, "x": 10, "y": 20 },
    { "page": 3, "x": 400, "y": 50 }
  ],
  "prefill_options": {
    "full_name": "John Doe",
    "mobile_number": "9876543210",
    "user_email": "[email protected]"
  }
}

Here is a sample JSON input (NSDL with stamp):

{
  "sign_type": "nsdl-with-stamp",
  "pdf_pre_uploaded": true,
  "pdf_url": "https://example.com/documents/employment_agreement.pdf",
  "config": {
    "reason": "Employment agreement",
    "stamp_paper_amount": 100,
    "stamp_paper_state": "maharashtra",
    "stamp_data": {
      "Name": "John Doe",
      "DOB": "1995-04-12",
      "Address": "12 MG Road, Pune",
      "Email": "[email protected]",
      "Mobile": "9876543210",
      "FathersName": "Richard Doe",
      "Occupation": "Software Engineer"
    }
  },
  "positions": [{ "page": 1, "x": 10, "y": 20 }]
}

Here is a sample JSON input (SureSign):

{
  "sign_type": "suresign",
  "pdf_pre_uploaded": false,
  "config": {
    "reason": "Policy acknowledgement"
  },
  "positions": [{ "page": 1, "x": 10, "y": 20 }],
  "prefill_options": {
    "full_name": "John Doe",
    "user_email": "[email protected]"
  }
}

Response

• Client ID (used by all the e-sign actions below)
• Redirect URL (signing link for the signer)
• E-sign session details

When PDF pre-uploaded is true, the response is wrapped as initialization (the details above) and uploadPdfResponse (the result of uploading the PDF from the PDF URL).

Get Upload Link

Returns a URL to upload the PDF for an e-sign request that was initialized with PDF pre-uploaded set to false.

Input Parameters

Mandatory

Here is a sample JSON input:

{
  "client_id": "esign_xxxxxxxxxxxxxxxx"
}

Response

• Upload URL
• URL expiry time
• Upload instructions

Get Status

Retrieves the current status of an e-sign request.

Input Parameters

Mandatory

Here is a sample JSON input:

{
  "client_id": "esign_xxxxxxxxxxxxxxxx"
}

Response

• Current e-sign status: client_initiated, otp_sent, otp_verified, esign_started, esign_completed, esign_failed
• Status timestamp
• Transaction details

Get Signed Document

Retrieves the signed PDF for a completed e-sign request.

Input Parameters

Mandatory

Here is a sample JSON input:

{
  "client_id": "esign_xxxxxxxxxxxxxxxx"
}

Response

• Download URL
• Signed PDF data
• Document metadata
• Signature details

Get Audit Trail

Retrieves the audit trail of an e-sign request for compliance and record-keeping.

Input Parameters

Mandatory

Here is a sample JSON input:

{
  "client_id": "esign_xxxxxxxxxxxxxxxx"
}

Response

• Detailed audit trail of signing events
• Timestamps for each action
• IP addresses and location data (if captured)
• User actions and verifications performed

Get Report

Generates a report for an e-sign request, such as matching the signer's name against the name on Aadhaar.

Input Parameters

Mandatory

Here is a sample JSON input:

{
  "client_id": "esign_xxxxxxxxxxxxxxxx",
  "categories": ["name_match"]
}

Response

• Report for the selected categories
• Name match results (if selected)
• Transaction summary
• Verification details