Skip to content

eSign API Integration Guide

Overview

The eSign API provides a REST interface for digitally signing PDF documents using Aadhaar-based authentication. The API supports both eSign 2.1 and eSign 3.2 signing modes with multiple authentication methods.

Base URL: https://your-domain.com/api/java/v1/esign

Supported Formats: XML (default) and JSON

Version: 1.0

Table of Contents

  1. Authentication
  2. Sign Document Endpoint
  3. Request Parameters
  4. Authentication Modes
  5. Signing Options
  6. Date Format Reference
  7. PDF Lock Modes
  8. Multi-Page Signing
  9. Signatory Checks
  10. Response Format
  11. Retrieve Signed Document
  12. Secure Transaction Lookup
  13. Webhook Callbacks
  14. Error Codes
  15. Transaction ID Uniqueness
  16. Complete Examples

1. Authentication

All requests must include authentication credentials in the auth block.

Field Type Required Description
command String Yes Must be "esign"
token String Yes Your API authentication token
key String Yes Your API key

2. Sign Document Endpoint

POST /api/java/v1/esign

Initiates a document signing request.

Headers:

Header Value Description
Content-Type application/xml or application/json Request format
Accept application/xml or application/json Response format

Explicit format endpoints (optional):

  • POST /api/java/v1/esign/json (JSON in, JSON out)
  • POST /api/java/v1/esign/xml (XML in, XML out)

3. Request Parameters

XML Format

<?xml version="1.0" encoding="UTF-8"?>
<request>
    <auth>
        <command>esign</command>
        <token>your-api-token</token>
        <key>your-api-key</key>
    </auth>
    <parameter>
        <uploadpdf>
            <pdf64>BASE64_ENCODED_PDF_CONTENT</pdf64>
            <title>Document Title</title>
            <mode>online-aadhaar-otp</mode>
            <txn>CLIENT_TRANSACTION_ID</txn>
            <signername>Signer Name</signername>
            <callbackurl>https://your-callback-url.com/webhook</callbackurl>
            <option>
                <cood>350,50,550,120</cood>
                <pagenum>all</pagenum>
                <reason>Digital Signature</reason>
                <location>India</location>
                <greenticked>y</greenticked>
                <dateformat>dd-MMM-yyyy hh:mm a</dateformat>
                <lockpdf>n</lockpdf>
            </option>
        </uploadpdf>
    </parameter>
</request>

JSON Format

{
    "auth": {
        "command": "esign",
        "token": "your-api-token",
        "key": "your-api-key"
    },
    "parameter": {
        "uploadpdf": {
            "pdf64": "BASE64_ENCODED_PDF_CONTENT",
            "title": "Document Title",
            "mode": "online-aadhaar-otp",
            "txn": "CLIENT_TRANSACTION_ID",
            "signername": "Signer Name",
            "callbackurl": "https://your-callback-url.com/webhook",
            "option": {
                "cood": "350,50,550,120",
                "pagenum": "all",
                "reason": "Digital Signature",
                "location": "India",
                "greenticked": "y",
                "dateformat": "dd-MMM-yyyy hh:mm a",
                "lockpdf": "n"
            }
        }
    }
}

Parameter Reference

Parameter Type Required Description
pdf64 String Yes Base64 encoded PDF document
pdfurl String No Alternative: URL to fetch PDF from (instead of pdf64)
title String Yes Document title (max 50 characters)
mode String Yes Authentication mode (see Modes)
txn String No Your transaction ID for tracking
signername String Yes Name of the signer
ekycid String Conditional eKYC ID (required for eSign 3.2 modes)
callbackurl String No Webhook URL for completion notification
option Object No Signing options (see Options)
checks Object No Signatory checks — pin the signer's Aadhaar attributes (see Signatory Checks)

4. Authentication Modes

The mode parameter specifies the Aadhaar authentication method.

Available Modes

Mode Description Version Authentication Method
online-aadhaar-otp OTP-based authentication eSign 2.1 User receives OTP on registered mobile
online-aadhaar-bio Biometric (Fingerprint) authentication eSign 2.1 User provides fingerprint scan
online-aadhaar-iris Iris scan authentication eSign 2.1 User provides iris scan
online-aadhaar-face Face authentication eSign 2.1 User provides face scan
capricorn-ekyc-account eKYC-based authentication eSign 3.2 Pre-verified Capricorn eKYC account

Mode Selection Guide

Use Case Recommended Mode
Remote signing (user not physically present) online-aadhaar-otp
In-person signing with fingerprint device online-aadhaar-bio
High-security environments online-aadhaar-iris
Modern biometric systems online-aadhaar-face
Pre-verified KYC customers capricorn-ekyc-account

Examples

OTP Mode (Most Common): 

<mode>online-aadhaar-otp</mode>

Biometric/Fingerprint Mode: 

<mode>online-aadhaar-bio</mode>

Iris Scan Mode: 

<mode>online-aadhaar-iris</mode>

Face Authentication Mode: 

<mode>online-aadhaar-face</mode>

Capricorn eKYC Account Mode (Requires ekycid): 

<mode>capricorn-ekyc-account</mode>
<ekycid>EKYC123456789</ekycid>

Mode Requirements

Mode Requires ekycid Requires Device User Interaction
online-aadhaar-otp No No Enter OTP from mobile
online-aadhaar-bio No Fingerprint scanner Place finger on scanner
online-aadhaar-iris No Iris scanner Look into scanner
online-aadhaar-face No Camera Face the camera
capricorn-ekyc-account Yes No Minimal (pre-verified)

5. Signing Options

The option block controls signature appearance and placement.

Option Type Default Description
cood String 350,50,550,120 Signature box coordinates: x1,y1,x2,y2
pagenum String 1 Page selection for signature
reason String - Reason for signing. No default — omitted from the signature entirely if not supplied
location String - Signing location. No default — omitted from the signature entirely if not supplied
customtext String - Custom text to display in signature
greenticked String y Show green checkmark icon: y or n
dateformat String dd-MMM-yyyy hh:mm a Date format in signature
lockpdf String n PDF lock mode (see Lock Modes)
signaturePositions Array - Multi-location positions (see Multi-Location Signing)
searchbytext String - Enable global search-by-text mode
boxsize String - Required in search-by-text mode. Format: width,height
boxposition String - Required in search-by-text mode. One of: top, bottom, left, right, on

Note: All signatures use PKCS7pdf format with Timestamp (TSA) and LTV (Long Term Validation) enabled by default. This ensures signatures include full certificate chain, cryptographic proof of signing time from a trusted Timestamp Authority, and remain valid for long-term verification even after certificate expiration.

Coordinate System

Coordinates define the signature box position on the PDF page:

(x1, y1) +---------------------+
         |                     |
         |   Signature Box     |
         |                     |
         +---------------------+ (x2, y2)
  • Origin (0,0): Bottom-left corner of the page
  • Units: Points (1 point = 1/72 inch)
  • Standard A4 page: 595 x 842 points

Common Placements:

Position Coordinates
Bottom-right 400,50,550,120
Bottom-left 50,50,200,120
Top-right 400,750,550,820
Center-bottom 200,50,400,120

6. Date Format Reference

The dateformat parameter controls how the signing date appears in the signature box.

Format Pattern Characters

Symbol Meaning Example
yyyy 4-digit year 2025
yy 2-digit year 25
MMMM Full month name January
MMM Abbreviated month Jan
MM 2-digit month 01
M Month without leading zero 1
dd 2-digit day 05
d Day without leading zero 5
EEEE Full day name Monday
EEE Abbreviated day Mon
HH 24-hour hour (00-23) 14
hh 12-hour hour (01-12) 02
h 12-hour without leading zero 2
mm Minutes 30
ss Seconds 45
a AM/PM marker PM
z Timezone IST
Z Timezone offset +0530

Common Date Formats

Format Pattern Example Output
dd-MMM-yyyy hh:mm a 05-Jan-2025 02:30 PM
dd/MM/yyyy HH:mm:ss 05/01/2025 14:30:45
yyyy-MM-dd HH:mm:ss 2025-01-05 14:30:45
dd-MM-yyyy 05-01-2025
MMMM dd, yyyy January 05, 2025
dd MMMM yyyy 05 January 2025
EEE, dd MMM yyyy Mon, 05 Jan 2025
EEEE, MMMM dd, yyyy Monday, January 05, 2025
yyyy/MM/dd 2025/01/05
dd.MM.yyyy 05.01.2025

Date + Time Formats

Format Pattern Example Output
dd-MMM-yyyy hh:mm a 05-Jan-2025 02:30 PM
dd-MMM-yyyy HH:mm 05-Jan-2025 14:30
dd/MM/yyyy hh:mm:ss a 05/01/2025 02:30:45 PM
yyyy-MM-dd'T'HH:mm:ss 2025-01-05T14:30:45
dd MMM yyyy, hh:mm a 05 Jan 2025, 02:30 PM
MMMM dd, yyyy 'at' hh:mm a January 05, 2025 at 02:30 PM
EEE dd-MMM-yyyy hh:mm a Mon 05-Jan-2025 02:30 PM

Regional Formats

Region Format Pattern Example Output
India dd-MMM-yyyy hh:mm a 05-Jan-2025 02:30 PM
US MM/dd/yyyy hh:mm a 01/05/2025 02:30 PM
UK dd/MM/yyyy HH:mm 05/01/2025 14:30
ISO 8601 yyyy-MM-dd'T'HH:mm:ssZ 2025-01-05T14:30:45+0530
Europe dd.MM.yyyy HH:mm 05.01.2025 14:30
Japan yyyy/MM/dd HH:mm 2025/01/05 14:30

Date Only Formats

Format Pattern Example Output
dd-MMM-yyyy 05-Jan-2025
dd/MM/yyyy 05/01/2025
MM/dd/yyyy 01/05/2025
yyyy-MM-dd 2025-01-05
dd MMMM yyyy 05 January 2025
MMMM dd, yyyy January 05, 2025
d MMM yyyy 5 Jan 2025

Time Only Formats

Format Pattern Example Output
hh:mm a 02:30 PM
HH:mm:ss 14:30:45
hh:mm:ss a 02:30:45 PM
HH:mm 14:30
h:mm a 2:30 PM

Special Characters in Format

Use single quotes to include literal text:

Format Pattern Example Output
'Signed on' dd-MMM-yyyy Signed on 05-Jan-2025
dd-MMM-yyyy 'at' hh:mm a 05-Jan-2025 at 02:30 PM
'Date:' dd/MM/yyyy Date: 05/01/2025

Examples in Request

Default Format: 

<option>
    <dateformat>dd-MMM-yyyy hh:mm a</dateformat>
</option>
Output: 05-Jan-2025 02:30 PM

ISO Format: 

<option>
    <dateformat>yyyy-MM-dd HH:mm:ss</dateformat>
</option>
Output: 2025-01-05 14:30:45

Formal Format: 

<option>
    <dateformat>EEEE, MMMM dd, yyyy 'at' hh:mm a</dateformat>
</option>
Output: Monday, January 05, 2025 at 02:30 PM

Date Only: 

<option>
    <dateformat>dd MMMM yyyy</dateformat>
</option>
Output: 05 January 2025

7. PDF Lock Modes

The lockpdf parameter controls document protection after signing.

Value Mode Description
n No Lock Allow additional signatures and modifications (default)
y Certified (No Changes) Most restrictive - no changes allowed after signing
cf Certified (Form Filling) Allow only form field filling
cfa Certified (Form Filling & Annotations) Allow form filling and adding annotations
ym Signature Lock Dictionary Lock document using PdfSigLockDictionary

Choosing the Right Lock Mode

Use Case Recommended Mode
Single signer, final document y (most secure)
Multiple signers needed n (no lock)
Fillable form that users complete after signing cf
Document needing review comments cfa
Legacy system compatibility ym

8. Multi-Page Signing

The pagenum option supports flexible page selection.

Value Description Example Result (5-page doc)
1 Single page Page 1 only
first First page Page 1
last Last page Page 5
all All pages Pages 1, 2, 3, 4, 5
1-3 Page range Pages 1, 2, 3
1,3,5 Specific pages Pages 1, 3, 5

8.1 Multi-Location Signing

Multi-location signing allows you to place signatures at different positions on different pages. This is useful when you need varying signature placements (e.g., bottom-right on page 1, center on page 3, etc.).

When to Use Multi-Location

Scenario Use
Same position on all pages Standard cood + pagenum
Different positions on different pages signaturePositions array
Signature on specific pages with specific coordinates signaturePositions array

Request Format

To use multi-location signing, set cood and pagenum to "custom" and provide a signaturePositions array:

JSON Format

{
    "auth": {
        "command": "esign",
        "token": "your-api-token",
        "key": "your-api-key"
    },
    "parameter": {
        "uploadpdf": {
            "pdf64": "BASE64_ENCODED_PDF_CONTENT",
            "title": "Multi-Location Contract",
            "mode": "online-aadhaar-otp",
            "txn": "CLIENT_TRANSACTION_ID",
            "signername": "Signer Name",
            "option": {
                "cood": "custom",
                "pagenum": "custom",
                "reason": "Digital Signature",
                "location": "India",
                "greenticked": "y",
                "lockpdf": "n",
                "signaturePositions": [
                    {
                        "pages": "first",
                        "cood": "50,50,200,120"
                    },
                    {
                        "pages": "last",
                        "cood": "400,50,550,120"
                    },
                    {
                        "pages": "2,3",
                        "cood": "200,400,400,470"
                    }
                ]
            }
        }
    }
}

XML Format

<?xml version="1.0" encoding="UTF-8"?>
<request>
    <auth>
        <command>esign</command>
        <token>your-api-token</token>
        <key>your-api-key</key>
    </auth>
    <parameter>
        <uploadpdf>
            <pdf64>BASE64_ENCODED_PDF_CONTENT</pdf64>
            <title>Multi-Location Contract</title>
            <mode>online-aadhaar-otp</mode>
            <txn>CLIENT_TRANSACTION_ID</txn>
            <signername>Signer Name</signername>
            <option>
                <cood>custom</cood>
                <pagenum>custom</pagenum>
                <reason>Digital Signature</reason>
                <location>India</location>
                <greenticked>y</greenticked>
                <lockpdf>n</lockpdf>
                <signaturePositions>
                    <position>
                        <pages>first</pages>
                        <cood>50,50,200,120</cood>
                    </position>
                    <position>
                        <pages>last</pages>
                        <cood>400,50,550,120</cood>
                    </position>
                    <position>
                        <pages>2,3</pages>
                        <cood>200,400,400,470</cood>
                    </position>
                </signaturePositions>
            </option>
        </uploadpdf>
    </parameter>
</request>

signaturePositions Array Reference

Each object in the signaturePositions array has:

Field Type Required Description
pages String Yes Page selection: "first", "last", "all", "1", "1-3", "1,3,5"
cood String Yes Coordinates for this position: "x1,y1,x2,y2"

Page Selection Values for signaturePositions

Value Description
"first" First page only
"last" Last page only
"all" All pages (same coordinates)
"1" Specific page number
"1-3" Page range (pages 1, 2, 3)
"1,3,5" Specific pages (comma-separated)

Important Rules

Required Settings for Multi-Location

When using signaturePositions, you must set:

  • cood = "custom"
  • pagenum = "custom"

If these are not set to "custom", the signaturePositions array will be ignored.

Multi-Location Examples

Example 1: Different corners on first and last page 

"signaturePositions": [
    { "pages": "first", "cood": "50,50,200,120" },
    { "pages": "last", "cood": "400,700,550,770" }
]

Example 2: Signature on specific pages with different positions 

"signaturePositions": [
    { "pages": "1", "cood": "350,50,500,120" },
    { "pages": "3", "cood": "50,400,200,470" },
    { "pages": "5", "cood": "350,400,500,470" }
]

Example 3: Same position on a range of pages, different on last 

"signaturePositions": [
    { "pages": "1-4", "cood": "350,50,500,120" },
    { "pages": "last", "cood": "200,50,400,120" }
]

Example 4: Multiple positions including all middle pages 

"signaturePositions": [
    { "pages": "first", "cood": "50,50,200,120" },
    { "pages": "2,3,4", "cood": "200,400,400,470" },
    { "pages": "last", "cood": "400,50,550,120" }
]

Validation Errors

Error Cause Solution
VAL-008 signaturePositions provided but cood != "custom" Set cood to "custom"
VAL-009 signaturePositions provided but pagenum != "custom" Set pagenum to "custom"
VAL-010 Empty signaturePositions array Add at least one position
VAL-011 Invalid page value in position Use valid page format
VAL-012 Invalid coordinates in position Use "x1,y1,x2,y2" format

8.2 Search By Text (Global Auto-Placement)

Enable automatic signature placement by searching text across all pages.

Requirements

  • pagenum = "searchbytext"
  • cood = "searchbytext"
  • searchbytext is required (PDF-level)
  • boxsize and boxposition are required
  • Any manual signaturePositions or manual coordinates are ignored in this mode

Behavior

  • Searches all pages
  • Case-insensitive, partial match
  • Signature is placed for each occurrence of the text
  • If text not found anywhere, request fails with validation error

XML Example

<option>
    <pagenum>searchbytext</pagenum>
    <cood>searchbytext</cood>
    <searchbytext>Authorized Signatory</searchbytext>
    <boxsize>220,80</boxsize>
    <boxposition>bottom</boxposition>
</option>

JSON Example

{
  "option": {
    "pagenum": "searchbytext",
    "cood": "searchbytext",
    "searchbytext": "Authorized Signatory",
    "boxsize": "220,80",
    "boxposition": "bottom"
  }
}

9. Signatory Checks

Signatory checks let you pin the Aadhaar attributes of whoever signs at the ESP. If the signer's attributes don't match what you specified, the signing is rejected and no signed PDF is produced.

Use this when you know who should be signing — e.g. a specific employee whose name and last-4-of-Aadhaar are on file. It is a complement to ESP authentication (OTP/biometric), not a replacement.

Provide a checks object (or <checks> element) as a sibling of option inside uploadpdf. At least one attribute other than pattern must be supplied.

Supported Attributes

Field Format Description
pattern E or P E = exact match (default). P = partial / substring match
signer 4 digits Last 4 digits of the signer's Aadhaar
name 1–100 chars (letters/spaces/dots/apostrophes/hyphens) Aadhaar name
email RFC 5321 email Aadhaar-linked email
phone 10-digit Indian mobile Aadhaar-linked phone
yob 4-digit year (1900–current) Year of birth
gender M or F Aadhaar gender
state 1–50 letters/spaces/dots/hyphens State name
pincode 6-digit Indian PIN Aadhaar address PIN code
country 2-letter ISO code or country name Country

Match Patterns

  • pattern=E (exact) — every supplied field must match exactly (text is case-insensitive). Use when you have authoritative HR records and want to detect any mismatch.
  • pattern=P (partial) — each supplied field must appear as a substring of the corresponding attribute (case-insensitive). e.g. name="John" matches "JOHN ALBERT DOE" but not "JANE DOE". Useful for short/common names where exact spelling varies.

JSON Format

{
    "auth": {
        "command": "esign",
        "token": "your-api-token",
        "key": "your-api-key"
    },
    "parameter": {
        "uploadpdf": {
            "pdf64": "BASE64_ENCODED_PDF_CONTENT",
            "title": "Contract",
            "mode": "online-aadhaar-otp",
            "txn": "CLIENT_TRANSACTION_ID",
            "signername": "John Doe",
            "option": {
                "cood": "350,50,550,120",
                "pagenum": "1"
            },
            "checks": {
                "pattern": "E",
                "signer": "1234",
                "name": "John Doe",
                "email": "john@example.com"
            }
        }
    }
}

XML Format

The <checks> element carries the fields as attributes, not child elements:

<?xml version="1.0" encoding="UTF-8"?>
<request>
    <auth>
        <command>esign</command>
        <token>your-api-token</token>
        <key>your-api-key</key>
    </auth>
    <parameter>
        <uploadpdf>
            <pdf64>BASE64_ENCODED_PDF_CONTENT</pdf64>
            <title>Contract</title>
            <mode>online-aadhaar-otp</mode>
            <txn>CLIENT_TRANSACTION_ID</txn>
            <signername>John Doe</signername>
            <checks pattern="E"
                    signer="1234"
                    name="John Doe"
                    email="john@example.com"/>
        </uploadpdf>
    </parameter>
</request>

How Enforcement Works

  1. The check fields are forwarded to the ESP alongside the eSign request.
  2. The ESP compares each supplied field to the signer's actual Aadhaar attributes.
  3. If any check fails, the signing is rejected and the signed PDF is not produced.
  4. Otherwise, signing proceeds normally.

If pattern is omitted it defaults to E. Invalid input is rejected up front with a Signatory Check error (e.g. no attribute supplied, or a pattern other than E/P).

When Not to Use

Scenario Why
Public flows where any Aadhaar holder might sign You don't know who signs in advance
Bulk consumer onboarding Names rarely match records exactly (case, accents, suffixes)
As your only auth check The ESP still performs OTP/biometric authentication

Best use case: internal workflows where you have authoritative signer data and want to detect impersonation.

10. Response Format

Success Response

{
    "success": "OK",
    "command": "esign",
    "requestid": "1702819200123456789",
    "date": "2025-01-05T10:30:00+05:30",
    "responsedata": {
        "response": {
            "txn": "CLIENT_TRANSACTION_ID",
            "reference": "a1b2c3d4e5f6",
            "redirecturl": "https://api.example.com/api/java/v1/esign/redirect/a1b2c3d4e5f6",
            "getsigneddocurl": "https://api.example.com/api/java/v1/esign/signed/a1b2c3d4e5f6?token=SHORT_LIVED_TOKEN"
        }
    }
}

11. Retrieve Signed Document

GET /api/java/v1/esign/signed/{reference}

Returns Base64 + pdfurl.
Security: accepts either: - short-lived token in query string, or - auth headers (X-Auth-Token, X-Auth-Key).

Example (direct open): 

https://your-domain.com/api/java/v1/esign/signed/{reference}?token=SHORT_LIVED_TOKEN

Response behavior (by status): - 200 with XML/JSON response containing signpdf64 and pdfurl - 202 when signing is in progress (status = PENDING) - 410 when signing failed (status = FAILED) - 404 when transaction or signed PDF is missing - 401 when auth/token is missing or invalid

GET /api/java/v1/esign/document/{reference}

Returns the signed PDF file directly.

Security: - Direct download requires a short-lived token in the URL, or auth headers.

Example (direct open): 

https://your-domain.com/api/java/v1/esign/document/{reference}?token=SHORT_LIVED_TOKEN

Response behavior (by status): - 200 with PDF bytes (signed document) - 202 when signing is in progress - 410 when signing failed - 404 when transaction or signed PDF is missing - 401 when auth/token is missing or invalid

12. Secure Transaction Lookup

POST /api/java/v1/esign/transaction

This is the single secured lookup endpoint. It accepts any one of:

  • <reference>
  • <transactionid>
  • <internaltxn>

It returns transactionStatus and pdfurl (and signpdf64 only when completed).
pdfurl is a tokenized download link that can be opened directly.

Lookup precedence: If multiple identifiers are provided, the lookup order is reference ? transactionid ? internaltxn.

XML Example 

<request>
    <auth>
        <token>your-api-token</token>
        <key>your-api-key</key>
    </auth>
    <reference>YOUR_REFERENCE</reference>
</request>

JSON Example 

{
    "auth": {
        "token": "your-api-token",
        "key": "your-api-key"
    },
    "transactionid": "YOUR_TXN"
}

13. Webhook Callbacks

If callbackurl is provided, a POST request is sent when signing completes or fails.

14. Error Codes

Authentication Errors

Code Description Solution
AUTH-001 Authentication info is missing Include auth block in request
AUTH-002 Token is required Provide auth.token
AUTH-003 Key is required Provide auth.key
AUTH-004 Invalid token Check api.auth.token in your request matches server config
AUTH-005 Invalid key Check api.auth.key in your request matches server config
AUTH-006 Invalid command Use a valid command value

Request Validation Errors

Code Description Solution
REQ-001 Request body is empty Send a valid JSON/XML payload
REQ-002 Parameter section is missing Include <parameter> / parameter
REQ-003 uploadpdf section is missing Include <uploadpdf> / uploadpdf
REQ-004 Either pdf64 or pdfurl is required Provide one of them
REQ-005 mode is required Provide a valid mode
REQ-006 Invalid mode Use a supported mode
REQ-007 ekycid is required (eKYC mode) Provide ekycid for eKYC modes
REQ-008 signername is required Provide a signer name

Signed Document Errors

Code Description Solution
PENDING Signing in progress Retry later
FAILED Signing failed Check ESP logs and retry
NOTFOUND Transaction or signed PDF not found Verify reference/txn
ERROR Unexpected server error Check server logs
AUTH-001 Missing auth/token Provide token or auth headers
AUTH-004 Invalid token Use correct token
AUTH-005 Invalid key Use correct key

SearchByText Errors

Code Description Solution
SBT-001 searchByText is required but missing or empty Provide searchbytext
SBT-002 Text not found in PDF Use a different search string
SBT-003 PDF has no extractable text Use a text-based PDF
SBT-004 pages/cood not set to searchByText Set both to searchByText
SBT-005 Invalid boxsize Use width,height with positive numbers
SBT-006 Invalid boxposition Use top, bottom, left, right, or on
SBT-999 SearchByText processing error Check server logs
REQ-009 title must not exceed 50 characters Shorten the title

Validation Errors

Code Description Solution
VAL-001 Invalid PDF data Ensure PDF is valid and properly Base64 encoded
VAL-002 Invalid signer name Provide a non-empty signer name
VAL-003 Invalid mode specified Use a supported mode
VAL-004 Invalid page selection Use 1, all, first, last, 1-3, or 1,3,5
VAL-005 Invalid coordinates Use x1,y1,x2,y2 with valid numbers
VAL-006 Title too long Title must be 50 characters or less
VAL-007 Invalid date format Check dateformat pattern
VAL-008 signaturePositions provided but cood is not custom Set cood=custom
VAL-009 signaturePositions provided but pagenum is not custom Set pagenum=custom
VAL-010 Empty signaturePositions array Provide at least one position
VAL-011 Invalid page value in position Fix the pages value
VAL-012 Invalid coordinates in position Fix the cood value

Signatory Check Errors

Code Description Solution
CHK-001 checks provided but no attribute to verify Supply at least one of signer, name, email, phone, yob, gender, state, pincode, country
CHK-002 Invalid pattern value Use E (exact) or P (partial)

A signer-attribute mismatch detected by the ESP is reported as an ESP error during callback processing (the signed PDF is not produced), not as a CHK-* validation error.

Transaction Errors

Code Description Solution
TXN-001 Transaction ID already used Use a unique transaction ID (see below)
TXN-002 Transaction not found Check reference/transaction ID
TXN-003 Transaction expired Start a new signing request

ESP (eSign Provider) Errors

Code Description Solution
ESP-901 Invalid Authentication Mode Check AuthMode
ESP-902 Invalid ASP ID. It cannot be Empty Configure ASP ID
ESP-903 Invalid ASP ID. It may not exist or may be inactive. Verify ASP ID
ESP-905 Document Hash not received Ensure hash is sent
ESP-906 UID Token does not match Check UID token
ESP-907 Request Time Stamp cannot be Empty Ensure timestamp is set
ESP-908 Request Time Stamp is not valid. Please check the server time. Sync server time
ESP-909 Transaction ID cannot be Empty Provide txn
ESP-910 Duplicate Transaction ID for the given ASP. Use unique txn
ESP-911 Input XML Signature verification failed. Verify XML signature
ESP-922 Invalid Signature on Input XML. Use correct certificate
ESP-944 User terminated eKYC process User canceled
ESP-945 User terminated eKYC process after OTP Generation User canceled after OTP
ESP-946 User interface page expired Restart signing
ESP-991 ESP Database Connectivity Error Retry later
ESP-992 Input XML Parsing Error. Validate XML
ESP-993 Error Parsing CA Response XML Retry or contact ESP
ESP-999 Unknown Error Contact ESP

Processing Errors

Code Description Solution
PROC-001 PDF data required Provide either pdf64 or pdfurl
PROC-002 Unsupported authentication mode Use a supported mode
PROC-003 PDF processing failed Check PDF integrity
PROC-004 Signature embedding failed Contact support
PROC-999 General processing error Retry or contact support

License Errors

Code Description Solution
LIC-001 License file not found Place eSignLicense in config/ folder
LIC-002 License expired Contact Capricorn for license renewal
LIC-003 License invalid Check license file is correct

Certificate Errors

Code Description Solution
CERT-001 Certificate file not found Place privatekey.pfx in config/ folder
CERT-002 Certificate password incorrect Check esign.certificate.password in config
CERT-003 Certificate expired Contact Capricorn for certificate renewal

System Errors

Code Description Solution
SYS-001 General system error Retry or contact support
SYS-002 Error fetching status Retry status lookup

Error Response Format

JSON Error Response: 

{
    "success": "FAIL",
    "errorcode": "TXN-001",
    "errormessage": "Transaction ID 'ORDER-12345' has already been used for a completed signing. Each transaction ID can only be used once. Please use a unique transaction ID."
}

XML Error Response: 

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <success>FAIL</success>
    <errorcode>TXN-001</errorcode>
    <errormessage>Transaction ID 'ORDER-12345' has already been used for a completed signing. Each transaction ID can only be used once. Please use a unique transaction ID.</errormessage>
</response>

15. Transaction ID Uniqueness

Overview

Once a PDF is successfully signed with a transaction ID (txn), that ID cannot be used again. This prevents duplicate signing and ensures each transaction is unique.

How It Works

  1. You send a request with txn: "ORDER-12345"
  2. User completes signing successfully
  3. Transaction ORDER-12345 is marked as COMPLETED
  4. Any future request with txn: "ORDER-12345" returns TXN-001 error

Best Practices for Transaction IDs

Practice Example
Use unique identifiers ORDER-12345, INV-2025-001, CONTRACT-ABC123
Include timestamp DOC-20251215-143052-001
Use UUID 550e8400-e29b-41d4-a716-446655440000
Prefix by document type LOAN-001, KYC-002, AGREEMENT-003

Handling TXN-001 Error

// JavaScript example
try {
    const result = await client.signDocument(request);
} catch (error) {
    if (error.code === 'TXN-001') {
        // Generate new transaction ID and retry
        request.txn = generateUniqueId();
        const result = await client.signDocument(request);
    }
}

16. Complete Examples

Example 1: OTP Mode

{
    "parameter": {
        "uploadpdf": {
            "pdf64": "...",
            "title": "Contract",
            "mode": "online-aadhaar-otp",
            "signername": "Rahul Sharma"
        }
    }
}

Example 2: Biometric Mode

{
    "parameter": {
        "uploadpdf": {
            "pdf64": "...",
            "title": "Loan Agreement",
            "mode": "online-aadhaar-bio",
            "signername": "Priya Patel",
            "option": {
                "lockpdf": "y"
            }
        }
    }
}

Example 3: Iris Mode

{
    "parameter": {
        "uploadpdf": {
            "pdf64": "...",
            "title": "Security Document",
            "mode": "online-aadhaar-iris",
            "signername": "Vikram Singh"
        }
    }
}

Example 4: Face Mode

{
    "parameter": {
        "uploadpdf": {
            "pdf64": "...",
            "title": "Verification",
            "mode": "online-aadhaar-face",
            "signername": "Anita Desai"
        }
    }
}

Example 5: Capricorn eKYC Account Mode

{
    "parameter": {
        "uploadpdf": {
            "pdf64": "...",
            "title": "KYC Document",
            "mode": "capricorn-ekyc-account",
            "ekycid": "EKYC123456789",
            "signername": "Amit Kumar"
        }
    }
}

Example 6: Multi-Location Signing

Sign different pages at different positions:

{
    "auth": {
        "command": "esign",
        "token": "your-api-token",
        "key": "your-api-key"
    },
    "parameter": {
        "uploadpdf": {
            "pdf64": "...",
            "title": "Multi-Page Agreement",
            "mode": "online-aadhaar-otp",
            "txn": "MULTI-LOC-001",
            "signername": "Rahul Sharma",
            "option": {
                "cood": "custom",
                "pagenum": "custom",
                "reason": "Digital Signature",
                "location": "Mumbai, India",
                "greenticked": "y",
                "dateformat": "dd-MMM-yyyy hh:mm a",
                "lockpdf": "n",
                "signaturePositions": [
                    {
                        "pages": "first",
                        "cood": "50,50,200,120"
                    },
                    {
                        "pages": "2,3,4",
                        "cood": "350,400,500,470"
                    },
                    {
                        "pages": "last",
                        "cood": "400,50,550,120"
                    }
                ]
            }
        }
    }
}

Example 7: Signatory Checks (Aadhaar attribute pinning)

Reject the signing unless the signer's Aadhaar name and last-4 match:

{
    "auth": {
        "command": "esign",
        "token": "your-api-token",
        "key": "your-api-key"
    },
    "parameter": {
        "uploadpdf": {
            "pdf64": "...",
            "title": "Employee Agreement",
            "mode": "online-aadhaar-otp",
            "txn": "CHK-DEMO-001",
            "signername": "Rahul Sharma",
            "checks": {
                "pattern": "E",
                "signer": "1234",
                "name": "Rahul Sharma"
            }
        }
    }
}

Support

Version: 1.0
Last Updated: December 2025