Papyrus
Papyrus Doc Docs
Sign in

Templates

Templates are the backbone of repeatable signing workflows. They let you define roles, field placement, field labels, and default values once, then reuse that structure for every new document.

Why templates matter

Templates give you a stable contract between your team and your integrations:

  • Roles define who should sign without tying the template to a specific person
  • Fields stay in consistent locations on the PDF
  • Field labels let your app write and read field values programmatically

If you plan to automate document creation, build a solid template first.

Create a template

You can start in two ways:

Upload new files

  1. Open Templates
  2. Click Upload Template
  3. Name the template
  4. Upload one or more PDF or DOCX files in the order they should appear
  5. Configure roles and fields in the editor

Save an existing document as a template

If you already configured a document manually:

  1. Open it in the editor
  2. Click Save as Template
  3. Choose a template name

Papyrus keeps the layout and field positions, but replaces real recipients with recipient roles.

Design strong recipient roles

A good role label should describe responsibility, not a person's identity.

Examples:

Document Good role labels
Lease Landlord, Tenant
Sales contract Buyer, Seller
Offer letter Employer, Employee
Simple waiver Signer

When you later create a document from the template, you map each role label to a real signer. For API-driven workflows, roleLabel is the stable mapping label, so avoid renaming roles casually once an integration depends on them.

Configure fields

After the combined PDF is in the template editor:

  1. Place each field on the page
  2. Assign it to the correct role
  3. Set required or optional behavior
  4. Configure any dropdown options
  5. Save the template

Glossary

Four terms describe how field values work, in templates and everywhere else:

  • Prefill field — a field assigned to no recipient. Its value is filled in during document preparation (web editor or API values) and is read-only at signing.
  • Recipient field — a field assigned to a recipient role, completed at signing. May carry a default value the signer can edit.
  • Field label (label) — a stable string address for a field, used by the API to write and read values. Auto-generated (for example text_1) when unset.
  • Default value — the initial editable value of a recipient field. At document creation a field's value resolves as: API values[label], then the template defaultValue, then empty.

Prefill fields

Assign a field to Prefill fields when the value changes per document and is typed in while preparing it — an hourly rate, a start date, a clause selection. Text, date, checkbox, and dropdown fields can be prefill fields; signatures always belong to a recipient.

When you create a document from the template, prefill fields appear in a Fill in before sending panel in the editor (and can also be filled by clicking the field on the page). Required prefill fields must be completed before the document can be sent. Signers see the values as fixed, read-only content and cannot change them.

To sign a document yourself, use Add myself in the recipients panel: it adds you as a normal signer, and when it's your turn (immediately with parallel signing, or when you're first in a sequential order) Send & Sign Now takes you straight to signing. Your signing email still goes out as a backup, so you can finish later if you navigate away first.

Prefill fields are not compatible with shareable links or Kiosk Mode, since no one prepares the document in those flows.

The restriction works in both directions: you cannot enable a link on a template that has prefill fields, and you cannot add prefill fields while a link or Kiosk Mode is active. Assign those fields to the recipient instead, or disable the link first.

Create-and-send API calls must supply every required prefill value unless the field has a satisfying template defaultValue.

Field labels

Every field — prefill and recipient alike, on templates and on documents — has a field label: a stable string address such as company_name. The API uses labels to write values at creation time (values), to update draft values (PATCH /documents/{document}/fields), and to read values back (include=fields).

Set an explicit label when the same kind of value will be passed repeatedly, such as:

  • company_name
  • customer_address
  • order_number
  • effective_date

Fields without an explicit label get an auto-generated one like text_1 or signature_2, distinct from existing labels in the template. Auto-generated labels are stable once assigned, but naming labels yourself makes integrations far easier to read — values property names match labels after trimming outer whitespace and ignoring letter case.

Compatible text, date, checkbox, or dropdown placements with the same label are linked. They must share the same type, owner/recipient, required setting, dropdown options, and value. The editor shows chain badges and placement counts, and the setup panel renders one row per label. Signature, initials, name, email, and date-signed fields cannot form linked groups.

Renaming a template label updates its API handle for future documents; existing documents retain their snapshot. To separate one placement, use Unlink this placement. Giving compatible placements the same label links them and uses that group's value. If the fields are incompatible, the editor explains which setting prevents the link.

Default values

A recipient field can carry a defaultValue: the value the field starts with at signing, which the signer can still edit. At document creation each field's initial value resolves in order: the API payload's values[label], then the template's defaultValue, then empty. The same precedence applies to prefill fields, where the resolved value is final rather than editable.

A template defaultValue on a required prefill field also counts at create-and-send time — the API only rejects the request if neither the payload nor the default satisfies the field. See API Authentication for the validation rules.

Date fields expect values in the ISO YYYY-MM-DD format (for example 2026-08-25) — the signer's date picker cannot display anything else. API values in any other format are rejected with a 422.

Set defaults in the template editor: prefill-field defaults in the Default values panel, and recipient-field defaults from the field's settings popover (click the field and use the Default value input). Defaults apply to text, date, checkbox, and dropdown fields — dropdown defaults are limited to the field's options.

Per-document starting values for recipient fields can still be set or overridden while the document is a draft: from the field's settings popover in the document editor, in the API values payload at creation, or via PATCH /documents/{document}/fields.

Create a document from a template

From the dashboard:

  1. Open the template
  2. Click New Document
  3. Name the new document
  4. Fill in real recipient details for each role
  5. Send it when ready

From the API:

  1. Fetch the template if you need its roles or fields
  2. Call the create-from-template endpoint
  3. Pass a recipients array where each recipient object includes a roleLabel
  4. Optionally pass name, signingOrder, values, externalId, expiresInDays, and delivery settings
  5. Pass send: false to create a draft you can finish later via the field update and send endpoints

For basic email signing, you can keep each recipient minimal: roleLabel, name, and email are enough unless you want extra signer authentication.

Use signingOrder: "parallel" when everyone can sign immediately. Use signingOrder: "sequential" when each signer must wait for the previous signer to finish.

For the HTTP details, use API Authentication and the API Reference.

Direct links are useful for self-serve signing, such as:

  • Intake packets
  • Waivers
  • Consent forms
  • Onboarding agreements

When a direct link is enabled:

  1. Papyrus generates a reusable public URL
  2. A signer opens the link and completes the flow
  3. Papyrus creates a new document from the template automatically

Direct links work best with single-recipient templates. For more controlled or multi-recipient flows, create documents from the API instead.

See Embed Integration for the embedding decision tree and security recommendations.

Use kiosk mode for shared in-person devices

Kiosk mode is a separate template setting for in-person signing stations. It generates a dedicated /k/TOKEN URL, uses its own welcome message, and can stay enabled even when the template's direct link is disabled.

Use kiosk mode when:

  • The same tablet, laptop, or front-desk device serves multiple signers
  • Email should be optional because the signer is present in person
  • The device should reset automatically after completion or inactivity

Kiosk mode also works best with single-recipient templates. It does not create an iframe embed URL; use the kiosk link directly on the shared device.

See Kiosk Mode for setup, PIN behavior, and reset timing.

Organize with filing rules

Set a template's default filing rule from its detail panel. Every document created from the template inherits that rule, so signed, voided, and declined documents file themselves into the right folders automatically. The choice can still be overridden on an individual document.

See Filing Rules for the full workflow.

Manage template changes safely

You can rename, edit, or delete templates from the templates area.

The important rule is:

  • Editing a template changes future documents
  • It does not change documents that were already created from it

That makes templates safe to evolve over time without rewriting existing audit history.

Finding templates later

Use the templates list to:

  • Search by template name
  • Sort by name or created date
  • Open the detail view for roles, field counts, and field labels

Where to go next

Last updated: October 14, 2026