Documenso Core Workflow B: Templates & Direct Signing
Overview
Create reusable templates, generate documents from templates with prefilled fields, and implement direct signing links for public/anonymous signers. Templates define the PDF, fields, and recipient roles once — then stamp out documents on demand.
Prerequisites
- Completed
documenso-core-workflow-a
- At least one PDF uploaded to Documenso as a template
- Understanding of recipient roles and field types
Instructions
Step 1: Create a Template via Dashboard
Templates are created in the Documenso UI:
- Navigate to Templates in the sidebar.
- Click Create Template and upload a PDF.
- Add placeholder recipients (e.g., "Signer 1", "Approver") — these become roles that get filled when creating documents from the template.
- Place fields on the PDF and assign them to placeholder recipients.
- Save the template and note the template ID from the URL.
Step 2: Create Document from Template (v1 REST API)
const templateId = 42;
const res = await fetch(
`https://app.documenso.com/api/v1/templates/${templateId}/create-document`,
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DOCUMENSO_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
title: "Service Agreement — Acme Corp",
recipients: [
{
email: "ceo@acme.com",
name: "Alice CEO",
role: "SIGNER",
},
],
prefillFields: [
{ id: "field_abc123", value: "2026-03-22" },
{ id: "field_def456", value: "Acme Corporation" },
],
}),
}
);
const document = await res.json();
console.log(`Created document ${document.documentId} from template ${templateId}`);
Step 3: Template Workflow Patterns
async function generateContracts(
templateId: number,
clients: Array<{ email: string; name: string; company: string }>
) {
const results = [];
for (const client of clients) {
const res = await fetch(
`https://app.documenso.com/api/v1/templates/${templateId}/create-document`,
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DOCUMENSO_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
title: `Service Agreement — ${client.company}`,
recipients: [
{ email: client.email, name: client.name, role: "SIGNER" },
],
}),
}
);
const doc = await res.json();
await fetch(
,
{
: ,
: { : },
}
);
results.({ : doc., : client. });
}
results;
}
Step 4: Direct Signing Links
Direct links let anyone sign without receiving an email — perfect for public forms, walk-in signers, or embedded flows.
Setup in Dashboard:
- Open a template.
- Click Direct Link in template settings.
- Choose which recipient role the direct link signer fills.
- Copy the generated URL.
Direct Link URL format:
https://app.documenso.com/sign/direct/{token}
Embedding a Direct Link in an iframe:
<iframe
src="https://app.documenso.com/sign/direct/abc123token"
width="100%"
height="800"
frameborder="0"
allow="clipboard-write"
></iframe>
Step 5: Embedded Signing with React
npm install @documenso/embed-react
import { EmbedDirectTemplate } from "@documenso/embed-react";
export function DirectSigningPage() {
return (
<EmbedDirectTemplate
token="your-direct-link-token"
host="https://app.documenso.com"
// Pre-fill recipient data
name="Jane Doe"
email="jane@example.com"
// Lock pre-filled fields so signer can't change them
lockName={true}
lockEmail={true}
// Callbacks
onDocumentReady={() => console.log("Document loaded")}
onDocumentCompleted={() => console.log("Signing complete!")}
onDocumentError={(err) => console.error("Error:", err)}
/>
);
}
Step 6: Embedded Authoring (Document Editor)
Let users create and edit documents directly in your app:
import { EmbedCreateDocument } from "@documenso/embed-react";
export function CreateDocumentPage() {
return (
<EmbedCreateDocument
presignToken="presign-token-from-api"
host="https://app.documenso.com"
onDocumentCreated={(doc) => {
console.log(`Document ${doc.documentId} created`);
}}
/>
);
}
Presign tokens are obtained from the API and expire after 1 hour by default.
Step 7: v2 Envelope API (Multi-Document)
The v2 API uses "envelopes" that can contain multiple documents:
const form = new FormData();
form.append("payload.title", "Multi-Doc Envelope");
form.append("payload.type", "DOCUMENT");
form.append("files", pdfBlob1, "contract.pdf");
form.append("files", pdfBlob2, "appendix.pdf");
const envelope = await fetch("https://app.documenso.com/api/v2/envelope/create", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.DOCUMENSO_API_KEY}` },
body: form,
});
const { envelopeId } = await envelope.json();
await fetch("https://app.documenso.com/api/v2/envelope/distribute", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DOCUMENSO_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ envelopeId }),
});
Template vs Direct Document Comparison
| Feature | Document (ad-hoc) | Template | Direct Link |
|---|
| PDF upload | Every time | Once | Once (via template) |
| Field placement | Every time | Once | Once (via template) |
| Recipient known upfront | Yes | Yes | No |
| Public/anonymous signing | No | No | Yes |
| Batch generation | Manual | API call per client | N/A |
| Embedding | SignDocument | DirectTemplate | iframe/embed |
Error Handling
| Error | Cause | Solution |
|---|
| Template not found (404) | Invalid template ID or deleted | Verify ID in dashboard URL |
| Recipient mismatch | Wrong number vs template roles | Match template's placeholder roles |
| Field not found for prefill | Invalid prefillFields[].id | GET template first, inspect field IDs |
| Direct link disabled | Feature not enabled on template | Enable in template settings |
| Presign token expired | Token older than 1 hour | Request a new presign token |
Resources
Next Steps
For error handling patterns, see documenso-common-errors.
