Surepass
Templates

Initialize Esign from template

View as Markdown
POST
/api/v1/esign/initialize-from-template

Start an Esign session using a previously saved template. The template contributes file_id, signer elements, and signer defaults; the request contributes top-level Esign options plus runtime signer data in the same order as the template's signers array.

  • Runtime signer count must match the template signer count.
  • element_values overrides template element values at runtime by template field_id; position and type still come from the template.
  • Template signer defaults are merged with runtime signer input before the normal initialize-esign validation flow runs.
  • full_name should be supplied, reason must be supplied unless saved in the template, and at least one of email or mobile must be present.
  • This endpoint creates a real Esign flow, just like initialize-esign.

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.

template_id*string

Template ID returned by POST /api/v1/templates/save.

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.

max_retry?integer

Maximum signing retries.

folder?string

Folder name to organize the session under.

allow_download?boolean

Allow downloading the signed document.

expiry_seconds?integer

Optional. Min 3600 (1 hour), max 2592000 (30 days).

Range3600 <= value <= 2592000
redirect_url?string

URL the signer is redirected to after completing the Esign.

backend?string

Signing backend to use.

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.

email_template_overrides?

Optional invite email branding overrides. When company_name is provided, the default Surepass logo and branding are hidden, allowing white-label emails.

signers*array<>

Count must match the template signer count, in the same order.

Items1 <= items

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/esign/initialize-from-template" \  -H "Content-Type: application/json" \  -d '{    "template_id": "template_xxx",    "sign_type": "suresign",    "auth_mode": 1,    "folder": "HR",    "allow_download": true,    "expiry_seconds": 7200,    "redirect_url": "https://example.com/esign/complete",    "email_template_overrides": {      "company_name": "Acme Corp"    },    "signers": [      {        "full_name": "Employer A",        "email": "employer@example.com",        "reason": "Employer sign",        "face_ref_file_id": "file_faceReferenceImage",        "notification": {          "invite": true,          "completion": true,          "whatsapp": true        },        "element_values": {          "field_xxx": "INV-1001",          "field_yyy": "now"        }      },      {        "full_name": "Employee B",        "email": "employee@example.com",        "reason": "Employee sign",        "name_match": true,        "element_values": {          "field_zzz": "Employee B"        }      }    ]  }'
{  "data": {    "client_id": "esign_xxx",    "status": "pending",    "file_id": "file_onwEUoMxnWhewUzodZeW",    "signers": [      {        "signer_id": "signer_xxx",        "eligible": true,        "invite_url": "https://signer.surepass.app/#token=...",        "sign_type": "suresign",        "full_name": "Employer A",        "email": "employer@example.com",        "reason": "Employer sign",        "status": "pending"      }    ]  },  "status_code": 200,  "message": "Success",  "success": true}

Update template PUT

Update an existing template. `name`, `folder`, `file_id`, and `signers` are all optional in the request body. - If `signers` is provided, it **replaces** the saved signer blueprint completely and new `field_id` values are generated for all elements. - If `signers` is omitted, existing signers are preserved. - If `file_id` is provided, it must belong to the authenticated user.

List state codes GET

List the state codes supported for stamp procurement.