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

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)

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	`Digital Signature`	Reason for signing
`location`	String	`India`	Signing location
`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. 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"
        }
    }
}

10. 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

11. 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"
}

12. Webhook Callbacks¶

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

13. 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

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>

14. 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¶

You send a request with txn: "ORDER-12345"
User completes signing successfully
Transaction ORDER-12345 is marked as COMPLETED
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);
    }
}

15. 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"
                    }
                ]
            }
        }
    }
}

Support¶

Version: 1.0
Last Updated: December 2025

eSign API Integration Guide¶

Overview¶

Table of Contents¶

1. Authentication¶

2. Sign Document Endpoint¶

POST /api/java/v1/esign¶

3. Request Parameters¶

XML Format¶

JSON Format¶

Parameter Reference¶

4. Authentication Modes¶

Available Modes¶

Mode Selection Guide¶

Examples¶

Mode Requirements¶

5. Signing Options¶

Coordinate System¶

6. Date Format Reference¶

Format Pattern Characters¶

Common Date Formats¶

Date + Time Formats¶

Regional Formats¶

Date Only Formats¶

Time Only Formats¶

Special Characters in Format¶

Examples in Request¶

7. PDF Lock Modes¶

Choosing the Right Lock Mode¶

8. Multi-Page Signing¶

8.1 Multi-Location Signing¶

When to Use Multi-Location¶

Request Format¶

JSON Format¶

XML Format¶

signaturePositions Array Reference¶

Page Selection Values for signaturePositions¶

Important Rules¶

Multi-Location Examples¶

Validation Errors¶

8.2 Search By Text (Global Auto-Placement)¶

Requirements¶

Behavior¶

XML Example¶

JSON Example¶

9. Response Format¶

Success Response¶

10. Retrieve Signed Document¶

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

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

11. Secure Transaction Lookup¶

POST /api/java/v1/esign/transaction¶

12. Webhook Callbacks¶

13. Error Codes¶

Authentication Errors¶

Request Validation Errors¶

Signed Document Errors¶

SearchByText Errors¶

Validation Errors¶

Transaction Errors¶

ESP (eSign Provider) Errors¶

Processing Errors¶

License Errors¶

Certificate Errors¶

System Errors¶

Error Response Format¶

14. Transaction ID Uniqueness¶

Overview¶

How It Works¶

Best Practices for Transaction IDs¶

Handling TXN-001 Error¶

15. Complete Examples¶

Example 1: OTP Mode¶

Example 2: Biometric Mode¶

Example 3: Iris Mode¶

Example 4: Face Mode¶

Example 5: Capricorn eKYC Account Mode¶

Example 6: Multi-Location Signing¶

Support¶

POST `/api/java/v1/esign`¶

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

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

POST `/api/java/v1/esign/transaction`¶