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",
        "mapping_key": "client_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
custom_fields	object	—	Prefill fields by mapping_key

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.

Prefilling fields

Use custom_fields to pre-populate field values when sending. Keys correspond to the mapping_key values on template fields (visible via GET /v1/templates/: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"}
    ],
    "custom_fields": {
      "client_name": "Jane Smith",
      "company_name": "Acme Corp"
    }
  }'

Only fields with a matching mapping_key are prefilled. Unmatched keys are silently ignored.

Roleless templates

Some templates (e.g. IRS W-9) have fields but no roles. When sending a roleless template, all fields are automatically assigned to the first signer. You don’t need to provide role or role_id — just include at least one signer:

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_w9",
    "signers": [
      {"name": "Jane Smith", "email": "jane@acme.com"}
    ],
    "custom_fields": {
      "taxpayer_name": "Jane Smith",
      "business_name": "Acme Corp",
      "address": "123 Main St, Springfield, IL 62701"
    }
  }'