Surepass
Templates

Save template

View as Markdown
POST
/api/v1/templates/save

Save a reusable template blueprint for a file. A template stores the source file_id and an ordered signers array, where each signer contains its own PDF elements and optional signer-level defaults.

  • signers is ordered: the first template signer maps to the first runtime signer supplied later in initialize-from-template, and so on.
  • Every signer must contain at least one signature element.
  • A field_id is generated automatically for each saved element and returned in template reads; those values are what initialize-from-template.signers[].element_values uses later.
  • file_id must belong to the authenticated user.

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.

name*string

Template name.

file_id*string

Must belong to the authenticated user.

folder?string

Folder name to organize the template under.

signers*array<>

Ordered array — the first template signer maps to the first runtime signer in initialize-from-template, and so on.

Items1 <= items

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/templates/save" \  -H "Content-Type: application/json" \  -d '{    "name": "Employment Offer Template",    "file_id": "file_onwEUoMxnWhewUzodZeW",    "folder": "HR",    "signers": [      {        "sign_type": "suresign",        "auth_mode": 1,        "max_retry": 1,        "reason": "Employer sign",        "verify_email": false,        "verify_mobile": false,        "elements": [          {            "x": 100,            "y": 120,            "page": 0,            "alignment": "center",            "type": "signature"          }        ]      },      {        "sign_type": "suresign",        "auth_mode": 1,        "reason": "Employee sign",        "verify_email": true,        "verify_location": true,        "location_source": "ip",        "enforce_geofence": true,        "latitude": 19.076,        "longitude": 72.8777,        "radius": 500,        "elements": [          {            "x": 100,            "y": 220,            "page": 0,            "alignment": "center",            "type": "signature"          }        ]      }    ]  }'
{  "status_code": 0,  "message": "string",  "success": true,  "data": {    "client_id": "string",    "name": "string",    "file_id": "string",    "folder": "string",    "signers": [      {        "sign_type": "aadhaar",        "auth_mode": 0,        "max_retry": 0,        "pfx_id": "string",        "reason": "string",        "verify_email": true,        "verify_mobile": true,        "accept_virtual_sign": true,        "verify_location": true,        "location_source": "device",        "enforce_geofence": true,        "latitude": 0,        "longitude": 0,        "radius": 0,        "elements": [          {            "x": 0,            "y": 0,            "page": 0,            "alignment": "string",            "type": "signature",            "field_id": "string",            "width": 0,            "height": 0,            "font_size": 0,            "format": "string",            "value": "string"          }        ]      }    ]  }}

Download signed PDF GET

Download the final signed PDF after the Esign session completes.

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.