Initialize eSign

Endpoint Overview

POST /api/v1/esign/initialize

Description

This endpoint initializes an electronic signature (eSign) process for documents. It allows you to set up an eSign session with various authentication modes, configure signature positions on the document, and receive tokens that can be used with the eSign SDK or redirected to users for completing the signature process.

Key Benefits

Seamless integration of electronic signatures into your application workflow

Support for multiple authentication methods (Aadhaar OTP and fingerprint-based)

Customizable signature positioning on documents

Pre-filling of user information to improve user experience

Use Cases

Financial Services

Real Estate

Human Resources

Digital onboarding for loan applications requiring legally binding signatures

Investment account opening with KYC compliance

Insurance policy issuance and claims processing

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

Request Body

Parameter	Type	Required	Description
pdf_pre_uploaded	Boolean	No	Indicates if PDF is being uploaded by merchant
callback_url	String	No	URL to redirect after eSign completion
sign_type	String	Yes	Type of signature (e.g., "hsm")
config	Object	Yes	Configuration for eSign process
config.auth_mode	String	Yes	Authentication mode: "1" for Aadhaar OTP, "2" for fingerprint
config.reason	String	Yes	Reason for signing the document
config.positions	Object	Yes	Defines signature positions on document pages
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

Example Request

{
    "pdf_pre_uploaded": false,
    "sign_type": "hsm",
    "config": {
        "auth_mode": "1",
        "reason": "Contract",
        "positions": {
            "1": [
                {
                    "x": 10,
                    "y": 20
                }
            ],
            "2": [
                {
                    "x": 0,
                    "y": 0
                }
            ]
        }
    },
    "prefill_options": {
        "full_name": "Munna Bhaiya",
        "mobile_number": "9876543210",
        "user_email": "abc@gmail.com"
    }
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the eSign session details
data.token	String	Token generated for use by SDK
data.client_id	String	Unique identifier for this eSign request
data.url	String	URL generated for use by SDK or direct customer access
message_code	String	Status code in text format
success	Boolean	Indicates if the request was successful
message	String	Human-readable status message
status_code	Integer	HTTP status code

Example Successful Response

{
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.ababtjtjnbaesergrtjnnfeW32rfWAFF1tgWs.UtugjhGuy567hjJHFGyi-m3JJn4-o",
        "client_id": "esign_HLiwHZZxuUjZLqylzzvU",
        "url": "https://esign-client.aadhaarkyc.io/?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.ababtjtjnbaesergrtjnnfeW32rfWAFF1tgWs.UtugjhGuy567hjJHFGyi-m3JJn4-o"
    },
    "message_code": "success",
    "success": true,
    "message": "User initialized successfully",
    "status_code": 200
}

Possible Error Responses

Authentication Error

Validation Error

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

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

Integration Best Practices

Security Recommendations

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

Implement proper error handling for failed authentication attempts

Use HTTPS for all API communications

Implement proper session management for the eSign flow

User Experience Guidelines

Clearly explain to users why they need to sign the document

Provide clear instructions on how to complete the eSign process

Ensure mobile responsiveness for the eSign flow

Implement proper callback handling to guide users after completion

Code Samples

cURL

Python

Node.js

Related APIs

Document Upload API: Upload documents for eSign processing

eSign Status API: Check the status of an eSign request

eSign Callback API: Receive notifications when eSign is completed

Compliance and Legal Considerations

Electronic signatures obtained through this API are compliant with the Information Technology Act, 2000 (IT Act) in India. When using Aadhaar-based authentication, ensure you have the necessary permissions and comply with UIDAI guidelines. Always obtain explicit consent from users before initiating the eSign process.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/esign/initialize' \ --header 'Content-Type: application/json' \ --data-raw '{ "pdf_pre_uploaded": false, "sign_type": "hsm", "config": { "auth_mode": "1", "reason": "Contract", "positions": { "1": [ { "x": 10, "y": 20 } ], "2": [ { "x": 0, "y": 0 } ] } }, "prefill_options": { "full_name": "Munna Bhaiya", "mobile_number": "9876543210", "user_email": "abc@gmail.com" } }'

{ "data": { "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.ababtjtjnbaesergrtjnnfeW32rfWAFF1tgWs.UtugjhGuy567hjJHFGyi-m3JJn4-o", "client_id": "esign_HLiwHZZxuUjZLqylzzvU", "url": "https://esign-client.aadhaarkyc.io/?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.ababtjtjnbaesergrtjnnfeW32rfWAFF1tgWs.UtugjhGuy567hjJHFGyi-m3JJn4-o" }, "message_code": "success", "success": true, "message": "User initialized successfully", "status_code": 200 }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Initialize HSM

Initialize eSign#

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