Manage and use templates

Templates store a PDF, recipient roles, field placements, and workflow settings. Each use creates a separate draft document. Subsequent template edits do not change existing documents.

All requests use Authorization: Bearer <api_key> and the /api/v1 base path. The API key's resolved workspace determines which templates are visible.

Workspace requests also honor live member permissions: templates.use for reading and using, templates.manage for management, and documents.create or documents.manageAll to create a document. Editing and deletion require ownership of the template.

Create and upload

Send this body to POST /templates:

{
  "name": "Customer agreement",
  "fileName": "agreement.pdf",
  "recipients": [
    { "id": "customer", "name": "Customer", "role": "signer", "order": 1, "signatureMethod": "electronic" }
  ],
  "formFields": [
    {
      "id": "company",
      "fieldKey": "company_name",
      "type": "text",
      "pageNumber": 1,
      "x": 40, "y": 80, "width": 200, "height": 24,
      "required": true,
      "assignee": { "type": "sender_prefill" }
    },
    {
      "id": "customer_signature",
      "fieldKey": "customer_signature",
      "type": "signature",
      "pageNumber": 1,
      "x": 40, "y": 400, "width": 200, "height": 50,
      "required": true,
      "assignee": { "type": "recipient", "templateRecipientId": "customer" }
    }
  ],
  "workflow": { "mode": "sequential" }
}

The response contains id, upload.url, upload.fields, expiresIn, and maxFileSize. POST a multipart form directly to upload.url containing every upload.fields entry, followed by the PDF as the final file part. Complete the upload before using the template.

Template recipients describe roles and do not require real contact details. Omit their IDs to generate them automatically, then retrieve them with GET /templates/{id}. When supplying recipient-assigned fields in the same request, provide explicit recipient IDs. Field IDs and field keys must be unique. Coordinates use PDF points and pages start at 1. Signature fields must belong to recipients.

Edit and manage

GET /templates/{id} includes recipients, workflow, formFields, status, and usage statistics. Send only the properties to change in PATCH /templates/{id}. Arrays replace their stored values; use formFields: [] to clear all fields. If replacing recipients, update any affected field assignments in the same request. Empty updates and invalid assignments return 400.

Archive with { "status": "archived" } and restore with { "status": "active" }. Lists show active templates by default; use status=archived to find archived templates. Duplicate with POST /templates/{id}/copies and a body such as { "newName": "Agreement copy" }. Deletion is permanent and returns 204 without a response body.

Use a template

Download the templates Postman collection. It defaults to staging. Set apiKey and templateId, then run Get Document Creation Payload to retrieve editable JSON for Create Document from Template.

Send this body to POST /templates/{id}/documents:

{
  "title": "Agreement for Example Ltd",
  "recipientMapping": [
    { "templateRecipientId": "customer", "name": "Jane Doe", "email": "jane@example.com" }
  ],
  "prefillValues": [
    { "fieldId": "company", "fieldKey": "company_name", "value": "Example Ltd" }
  ]
}

Provide exactly one mapping for every recipient, with a real email or phone number. Sender-prefill entries must match both the field ID and key. Required prefill fields need a value or a stored default. Unknown or repeated entries return 400; archived templates return 409.

The 201 response includes envelopeId and status: "draft". Review the draft and send it with POST /documents/{envelopeId}/send using an API key with signing:write and, for workspace requests, the documents.send permission.

Get a generation request body

Call GET /templates/{id}/document-payload to get an editable JSON body for POST /templates/{id}/documents. The response includes the title, exactly one recipientMapping entry per template role, and prefillValues for sender-owned fields. Recipient IDs and field IDs/keys come from the saved template. Defaults (including false and 0) are preserved. Recipient-owned fields are excluded.

Replace the example recipient names/emails with real contacts, and fill in any empty sender-prefill values before submitting. You can supply phone for phone-only recipients and omit email. Workflow settings are inherited from the template; add workflow only when overriding them. This endpoint is read-only and can inspect archived or incomplete templates; generating a document still requires an active template with at least one signer and at most 15 recipients across all roles, including approvers and CC.