Using Templates

Templates let you define a document with pre-placed fields and named roles. When sending, you map real signers to the template roles instead of placing fields manually each time.

How templates work

1. Create a template in the VisiSign dashboard — upload a PDF, define roles (e.g. “client”, “witness”), and place fields on the document.
2. Via the API, send a signature request using the template ID and provide signer details for each role.
3. VisiSign creates a copy of the document with the fields pre-placed, then sends it for signature.

List templates

curl https://api.visisign.app/v1/templates \
  -H "Authorization: Bearer vsk_your_key_here"

{
  "templates": [
    {
      "id": "tmpl_123",
      "name": "NDA Template",
      "description": "Standard non-disclosure agreement",
      "signing_order": "everyone",
      "roles_count": 2,
      "fields_count": 5,
      "created_at": "2026-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "total_count": 1
  }
}

View template details

Get a template’s roles and fields:

curl https://api.visisign.app/v1/templates/tmpl_123 \
  -H "Authorization: Bearer vsk_your_key_here"

{
  "template": {
    "id": "tmpl_123",
    "name": "NDA Template",
    "roles": [
      {"id": 1, "name": "client", "order": 0},
      {"id": 2, "name": "witness", "order": 1}
    ],
    "fields": [
      {
        "id": 456,
        "role_id": 1,
        "role_name": "client",
        "field_type": "signature",
        "page": 1,
        "x": 100,
        "y": 650,
        "width": 200,
        "height": 50,
        "required": true
      }
    ]
  }
}

Send with a template

Map real signers to template roles using role (role name) or role_id:

curl -X POST https://api.visisign.app/v1/signature_requests/send_with_template \
  -H "Authorization: Bearer vsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tmpl_123",
    "title": "NDA — Acme Corp",
    "signers": [
      {"name": "Jane Smith", "email": "jane@acme.com", "role": "client"},
      {"name": "John Doe", "email": "john@example.com", "role": "witness"}
    ]
  }'

Parameters

Field	Type	Default	Description
template_id	string	required	Template ID (prefixed tmpl_)
title	string	template name	Document title
message	string	—	Message for signers
signers	array	required	Signers mapped to roles
expires_at	string	—	ISO 8601 expiration
test_mode	boolean	false	Non-binding test mode
metadata	object	—	Arbitrary metadata

Each signer needs name, email, and either role (role name) or role_id (role ID from the template).

The response is the same signature_request object as a regular send.