Initialize eSign with Stamp

Endpoint Overview

POST /api/v1/esign/initialize

Description

This API endpoint initializes an electronic signature (eSign) process with optional stamp paper integration. It allows you to set up a digital document signing workflow with various authentication methods, including Aadhaar OTP, fingerprint, iris, or face matching. The API generates a unique client ID, token, and URL that can be used to direct users to the eSign interface.

Key Benefits

Supports multiple authentication modes for secure digital signatures

Integrates stamp paper functionality for legally binding documents

Provides flexible configuration options for signature positioning and user experience

Enables seamless callback integration with your application workflow

Use Cases

Financial Services

Real Estate

Legal Services

Digital loan agreement signing with legal stamp paper integration

Investment account opening with KYC and signature verification

Insurance policy issuance with authenticated digital signatures

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 (JWT format)
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
file_id	String	Yes	Uploaded PDF file ID
send_email	Boolean	Yes	Send Invite Email
pdf_pre_uploaded	Boolean	No	Set to `true` if PDF is being uploaded by merchant
callback_url	String	No	URL to redirect after eSign completion
redirect_url	String	No	Optional redirect URL
config	Object	Yes	Configuration settings for the eSign process
config.accept_selfie	Boolean	No	Allow selfie capture during the process
config.allow_selfie_upload	Boolean	No	Allow users to upload selfies
config.accept_virtual_sign	Boolean	No	Enable virtual signature option
config.track_location	Boolean	No	Track user's location during signing
config.auth_mode	String	Yes	Authentication mode (1-4)
config.reason	String	Yes	Purpose of the signature
config.positions	Object	Yes	Coordinates for signature placement
config.stamp_paper_amount	Integer	No	Amount for stamp paper (required for stamped eSign)
config.stamp_paper_state	String	No	State for stamp paper (required for stamped eSign)
config.stamp_data	Object	No	Additional data to include on stamp paper
prefill_options	Object	No	Pre-filled user information
prefill_options.full_name	String	No	User's full name
prefill_options.mobile_number	String	No	User's mobile number
prefill_options.user_email	String	No	User's email address
previous_client_id	String	Yes	Previous client client_id for multi esign
testing_mode	Boolean	Yes	For sending link with test domain
aadhaar_esign_backend	String	No	Backend
expiry_minutes	Integer	No	Expiry minutes
sign_type	String	Yes	Type of sign
state	String	No	Client redirect state

Authentication Modes

Auth Mode 1: Aadhaar OTP based eSign

Auth Mode 2: Fingerprint based eSign

Auth Mode 3: Iris based eSign

Auth Mode 4: Face Match based eSign

Example Request

{
    "pdf_pre_uploaded": false,
    "callback_url": "https://example.com?state=test",
    "config": {
        "accept_selfie": true,
        "allow_selfie_upload": true,
        "accept_virtual_sign": true,
        "track_location": true,
        "auth_mode": "1",
        "reason": "Contract",
        "positions": {
            "1": [
                {
                    "x": 10,
                    "y": 20
                }
            ]
        },
        "stamp_paper_amount": 100,
        "stamp_paper_state": "Maharashtra",
        "stamp_data": {
            "Name": "John Doe",
            "DOB": "January 1, 1985",
            "Address": "123 Main Street, Springfield, IL, USA",
            "Passport Number": "X12345678",
            "Email": "john.doe@example.com",
            "Mobile": "+1 (123) 456-7890",
            "Mother's Name": "Jane Doe",
            "Father's Name": "James Doe",
            "Occupation": "Software Developer",
            "Work Address": "456 Elm Street, Springfield, IL, USA"
        }
    },
    "prefill_options": {
        "full_name": "Munna Bhaiya",
        "mobile_number": "9876543210",
        "user_email": "karankapoor229@gmail.com"
    }
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the response data
data.client_id	String	Unique identifier for this eSign request
data.group_id	String/null	Group identifier (if applicable)
data.token	String	JWT token for SDK authentication
data.url	String	URL to redirect users for completing the eSign process
status_code	Number	HTTP status code
message_code	String	Status message code
message	String	Human-readable status message
success	Boolean	Indicates if the request was successful

Example Successful Response

{
    "data": {
        "client_id": "esign_qXEdSjadoLIewCeTkcCa",
        "group_id": null,
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTcxMjM1MzYwNCwianRpIjoiZmYwYzcyNzYtOTJjMi00ZjNmLTgwYjgtMGNhZjNiOTk0ODkxIiwidHlwZSI6ImFjY2VzcyIsImlkZW50aXR5IjoiZXNpZ25fcVhFZFNqYWRvTElld0NlVGtjQ2EiLCJuYmYiOjE3MTIzNTM2MDQsImV4cCI6MTcxMjk1ODQwNCwidXNlcl9jbGFpbXMiOnsiZ2F0ZXdheSI6InNhbmRib3gifX0.vsI5Y-UQCKrxMqwECviORA_iSDqO4RMaaGGi5_IQ1L4",
        "url": "https://esign-client.surepass.io/?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTcxMjM1MzYwNCwianRpIjoiZmYwYzcyNzYtOTJjMi00ZjNmLTgwYjgtMGNhZjNiOTk0ODkxIiwidHlwZSI6ImFjY2VzcyIsImlkZW50aXR5IjoiZXNpZ25fcVhFZFNqYWRvTElld0NlVGtjQ2EiLCJuYmYiOjE3MTIzNTM2MDQsImV4cCI6MTcxMjk1ODQwNCwidXNlcl9jbGFpbXMiOnsiZ2F0ZXdheSI6InNhbmRib3gifX0.vsI5Y-UQCKrxMqwECviORA_iSDqO4RMaaGGi5_IQ1L4"
    },
    "status_code": 200,
    "message_code": "success",
    "message": "User initialized successfully",
    "success": true
}

Possible Error Responses

Authentication Error

Validation Error

{
    "status_code": 401,
    "message_code": "unauthorized",
    "message": "Invalid or expired token",
    "success": false
}

This error occurs when the 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 proper error handling for failed authentication attempts

Validate callback URLs to prevent open redirect vulnerabilities

Use HTTPS for all API communications to ensure data encryption

User Experience Guidelines

Provide clear instructions to users before redirecting them to the eSign URL

Implement proper loading states while the eSign process initializes

Handle callback responses gracefully to provide feedback to users

Pre-fill user information when possible to reduce friction

Code Samples

cURL

Python

Node.js

Related APIs

eSign Status API: Check the status of an eSign request

eSign Document Download API: Retrieve signed documents

eSign Callback Configuration API: Configure webhook notifications

Compliance and Legal Considerations

The eSign process complies with the Information Technology Act, 2000 and the Electronic Signature or Electronic Authentication Technique and Procedure Rules, 2015. When using stamp paper functionality, ensure compliance with the Indian Stamp Act and respective state stamp acts. Different states have different stamp duty requirements, so verify the appropriate stamp paper amount for your specific use case.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/esign/initialize' \ --header 'Content-Type: application/json' \ --data-raw '{ "pdf_pre_uploaded": false, "callback_url": "https://example.com?state=test", "config": { "accept_selfie": true, "allow_selfie_upload": true, "accept_virtual_sign": true, "track_location": true, "auth_mode": "1", "reason": "Contract", "positions": { "1": [ { "x": 10, "y": 20 } ] }, "stamp_paper_amount": 100, "stamp_paper_state": "Maharashtra", "stamp_data": { "Name": "John Doe", "DOB": "January 1, 1985", "Address": "123 Main Street, Springfield, IL, USA", "Passport Number": "X12345678", "Email": "john.doe@example.com", "Mobile": "+1 (123) 456-7890", "Mother'\''s Name": "Jane Doe", "Father'\''s Name": "James Doe", "Occupation": "Software Developer", "Work Address": "456 Elm Street, Springfield, IL, USA" } }, "prefill_options": { "full_name": "Munna Bhaiya", "mobile_number": "9876543210", "user_email": "karankapoor229@gmail.com" } }'

{ "data": { "client_id": "esign_qXEdSjadoLIewCeTkcCa", "group_id": null, "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTcxMjM1MzYwNCwianRpIjoiZmYwYzcyNzYtOTJjMi00ZjNmLTgwYjgtMGNhZjNiOTk0ODkxIiwidHlwZSI6ImFjY2VzcyIsImlkZW50aXR5IjoiZXNpZ25fcVhFZFNqYWRvTElld0NlVGtjQ2EiLCJuYmYiOjE3MTIzNTM2MDQsImV4cCI6MTcxMjk1ODQwNCwidXNlcl9jbGFpbXMiOnsiZ2F0ZXdheSI6InNhbmRib3gifX0.vsI5Y-UQCKrxMqwECviORA_iSDqO4RMaaGGi5_IQ1L4", "url": "https://esign-client.surepass.io/?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTcxMjM1MzYwNCwianRpIjoiZmYwYzcyNzYtOTJjMi00ZjNmLTgwYjgtMGNhZjNiOTk0ODkxIiwidHlwZSI6ImFjY2VzcyIsImlkZW50aXR5IjoiZXNpZ25fcVhFZFNqYWRvTElld0NlVGtjQ2EiLCJuYmYiOjE3MTIzNTM2MDQsImV4cCI6MTcxMjk1ODQwNCwidXNlcl9jbGFpbXMiOnsiZ2F0ZXdheSI6InNhbmRib3gifX0.vsI5Y-UQCKrxMqwECviORA_iSDqO4RMaaGGi5_IQ1L4" }, "status_code": 200, "message_code": "success", "message": "User initialized successfully", "success": true }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Initialize NSDL with Stamp

Initialize eSign with Stamp#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Authentication Modes#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses