Esign
Initialize Esign
Start an Esign session for one or more signers on an uploaded document.
pageinside elements is zero-indexed:0is the first page.- Multiple elements can be added per signer on different pages.
email_template_overridescustomizes invite email branding; whencompany_nameis provided, default Surepass branding is hidden for white-label emails.stampoptionally reserves e-stamps into the flow — either by search (amount+state_code+article_id, optionally narrowed by party names) or by explicitstamp_instance_ids. Reserved stamp PDFs are prefixed to the uploaded PDF before signing starts.
Authorization
bearerAuth AuthorizationBearer <token>
Bearer token authentication — paste your access token below.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
sign_type*SignType
aadhaar — OTP-based Aadhaar Esign. suresign — auto-signing by
Surepass. pfx — PFX-certificate signing (requires pfx_id).
Value in
- "aadhaar"
- "suresign"
- "pfx"
auth_mode?integer
Authentication mode for the signing session.
file_id*string
File ID returned by POST /api/v1/files/upload-pdf.
folder?string
Folder name to organize the session under.
expiry_seconds?integer
Session expiry. Min 3600 (1 hour), max 2592000 (30 days).
Range
3600 <= value <= 2592000email_template_overrides?
Optional invite email branding overrides. When company_name is
provided, the default Surepass logo and branding are hidden, allowing
white-label emails.
stamp?
Optional e-stamping configuration. Use either the amount-based
reservation flow (amount + state_code + article_id, required
together) or pass pre-reserved stamp_instance_ids.
signers*array<>
Items
1 <= itemsResponse Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/esign/initialize-esign" \ -H "Content-Type: application/json" \ -d '{ "sign_type": "aadhaar", "auth_mode": 1, "file_id": "file_onwEUoMxnWhewUzodZeW", "folder": "lehddsun", "expiry_seconds": 7200, "email_template_overrides": { "company_name": "Acme Corp", "legal_name": "Acme Corporation Pvt Ltd.", "support_email": "support@acme.com" }, "signers": [ { "full_name": "Test1", "email": "test1@example.com", "reason": "Test1 Sign", "verify_email": false, "verify_mobile": false, "name_match": true, "face_ref_file_id": "file_faceReferenceImage", "face_match_threshold": 80, "face_max_attempts": 5, "notification": { "invite": true, "completion": true, "whatsapp": true }, "elements": [ { "x": 100, "y": 10, "page": 0, "type": "signature", "allow_wet_signature": false } ] }, { "full_name": "Test2", "email": "test2@example.com", "mobile": "2222222222", "reason": "Test2 Sign", "verify_email": true, "verify_mobile": false, "notification": { "invite": false, "completion": true, "whatsapp": false }, "elements": [ { "x": 100, "y": 10, "page": 0, "type": "signature" } ] } ] }'{ "status_code": 0, "message": "string", "success": true, "data": { "actor_id": "string", "actor_type": "user", "allow_download": true, "archived": true, "auth_mode": [ 1 ], "backend": "nsdl", "client_id": "string", "created_at": "2019-08-24T14:15:22Z", "current_pdf_file_id": "string", "email_template_overrides": { "company_name": "string", "legal_name": "string", "support_email": "string" }, "expiry_seconds": 0, "file_id": "string", "filename": "string", "folder": "string", "max_retry": 0, "redirect_url": "http://example.com", "sender": "string", "sign_type": "aadhaar", "signers": [ { "signer_id": "string", "eligible": true, "invite_url": "http://example.com", "token": "string", "sign_type": "aadhaar", "auth_mode": [ 1 ], "max_retry": 0, "pfx_id": "string", "full_name": "string", "email": "user@example.com", "country_code": "string", "mobile": "string", "verify_email": true, "verify_mobile": true, "reason": "string", "accept_virtual_sign": true, "status": "pending", "elements": [ { "field_id": "string", "x": 0, "y": 0, "page": 0, "type": "signature", "alignment": "left", "width": 0, "height": 0, "allow_wet_signature": true, "font_size": 0, "format": "string", "value": "string" } ], "aadhaar_cert_details": { "name": "string", "country": "string", "state": "string", "pin_code": "string", "aadhaar": "string", "year_of_birth": "string", "gender": "string" }, "verify_location": true, "location_source": "device", "enforce_geofence": true, "latitude": 0, "longitude": 0, "radius": 0, "name_match": { "enforce": true, "prefill_name": "string", "signer_name": "string", "score": 0, "status": "pending" }, "face_match": { "enforce": true, "ref_file_id": "string", "live_file_id": "string", "match_threshold": 0, "max_attempts": 0, "liveness_score": 0, "match_score": 0 }, "notification": { "invite": true, "completion": true, "whatsapp": true } } ], "status": "pending" }}