Documenso Core Workflow A

Documenso Core Workflow A: Document Creation & Recipients

Output

• A role-limited document/recipient workflow with validated metadata, lifecycle, authorization, and redacted audit result.
• A safe disable/rollback path for an incorrect recipient, permission, or state transition.

Examples

Create a synthetic development document, assign a test recipient with the minimum required role, verify expiration/authentication/callback behavior, and archive it after the check. If role or recipient behavior is wrong, disable the workflow and correct it before promotion; do not substitute a real signer for the test.

Overview

Complete workflow for creating documents, managing recipients with different roles, positioning fields, and controlling signing order. Covers both the SDK and v1 REST API for document-centric operations.

Prerequisites

• Completed documenso-install-auth setup
• Understanding of documenso-sdk-patterns
• PDF file ready for signing

Instructions

Step 1: Create a Document with the SDK

import { Documenso } from "@documenso/sdk-typescript";
import { readFileSync } from "fs";

const client = new Documenso({ apiKey: process.env.DOCUMENSO_API_KEY! });

// Create document shell
const doc = await client.documents.createV0({
  title: "Service Agreement — Q1 2026",
});

// Upload PDF
const pdf = readFileSync("./contracts/service-agreement.pdf");
await client.documents.setFileV0(doc.documentId, {
  file: new Blob([pdf], { type: "application/pdf" }),
});

Step 2: Recipient Roles

Documenso supports these recipient roles:

// Add multiple recipients with roles
const signer = await client.documentsRecipients.createV0(doc.documentId, {
  email: "ceo@acme.com",
  name: "Alice CEO",
  role: "SIGNER",
});

const approver = await client.documentsRecipients.createV0(doc.documentId, {
  email: "legal@acme.com",
  name: "Legal Team",
  role: "APPROVER",
});

const cc = await client.documentsRecipients.createV0(doc.documentId, {
  email: "records@acme.com",
  name: "Records",
  role: "CC",
});

Step 3: Signing Order

Control the sequence in which recipients act. Lower numbers go first.

// Sequential signing: legal approves, then CEO signs
await client.documentsRecipients.createV0(doc.documentId, {
  email: "legal@acme.com",
  name: "Legal",
  role: "APPROVER",
  signingOrder: 1, // Goes first
});

await client.documentsRecipients.createV0(doc.documentId, {
  email: "ceo@acme.com",
  name: "CEO",
  role: "SIGNER",
  signingOrder: 2, // Goes after legal approves
});

Step 4: Add Fields to Document

Field coordinates use percentage-based positioning (0-100 for both X and Y axes). The origin is the top-left corner of the page.

// Signature field — bottom of page 1
await client.documentsFields.createV0(doc.documentId, {
  recipientId: signer.recipientId,
  type: "SIGNATURE",
  pageNumber: 1,
  pageX: 10,      // 10% from left
  pageY: 85,      // 85% from top
  pageWidth: 30,  // 30% of page width
  pageHeight: 5,  // 5% of page height
});

// Date field — next to signature
await client.documentsFields.createV0(doc.documentId, {
  recipientId: signer.recipientId,
  type: "DATE",
  pageNumber: 1,
  pageX: 60,
  pageY: 85,
  pageWidth: 20,
  pageHeight: 3,
});

// Name field — auto-filled from recipient
await client.documentsFields.createV0(doc.documentId, {
  recipientId: signer.recipientId,
  type: "NAME",
  pageNumber: 1,
  pageX: 10,
  pageY: 78,
  pageWidth: 30,
  pageHeight: 3,
});

// Text field — custom input (e.g., title/position)
await client.documentsFields.createV0(doc.documentId, {
  recipientId: signer.recipientId,
  type: "TEXT",
  pageNumber: 1,
  pageX: 60,
  pageY: 78,
  pageWidth: 30,
  pageHeight: 3,
});

Step 5: Multi-Page Document with Multiple Signers

async function createMultiSignerContract(
  pdfPath: string,
  signers: Array<{ email: string; name: string; signPage: number }>
) {
  const client = new Documenso({ apiKey: process.env.DOCUMENSO_API_KEY! });
  const doc = await client.documents.createV0({ title: "Multi-Party Agreement" });
  const pdf = readFileSync(pdfPath);
  await client.documents.setFileV0(doc.documentId, {
    file: new Blob([pdf], { type: "application/pdf" }),
  });

  for (let i = 0; i < signers.length; i++) {
    const s = signers[i];
    const recip = await client.documentsRecipients.createV0(doc.documentId, {
      email: s.email,
      name: s.name,
      role: "SIGNER",
      signingOrder: i + 1,
    });

    // Each signer gets signature + date on their assigned page
    await client.documentsFields.createV0(doc.documentId, {
      recipientId: recip.recipientId,
      type: "SIGNATURE",
      pageNumber: s.signPage,
      pageX: 10, pageY: 80, pageWidth: 30, pageHeight: 5,
    });
    await client.documentsFields.createV0(doc.documentId, {
      recipientId: recip.recipientId,
      type: "DATE",
      pageNumber: s.signPage,
      pageX: 60, pageY: 80, pageWidth: 20, pageHeight: 3,
    });
  }

  await client.documents.sendV0(doc.documentId);
  return doc.documentId;
}

Step 6: Document Metadata and Settings

// v1 REST API: create document with metadata
const res = await fetch("https://app.documenso.com/api/v1/documents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DOCUMENSO_API_KEY}`,
  },
  body: (() => {
    const form = new FormData();
    form.append("title", "NDA — Confidential");
    form.append("file", new Blob([pdf], { type: "application/pdf" }));
    return form;
  })(),
});
const document = await res.json();

Step 7: Query and Filter Documents

// List documents with pagination
const { documents } = await client.documents.findV0({
  page: 1,
  perPage: 20,
  orderByColumn: "createdAt",
  orderByDirection: "desc",
});

// Get single document with all details
const detail = await client.documents.getV0(documentId);
console.log(`Status: ${detail.status}`);   // DRAFT | PENDING | COMPLETED
console.log(`Recipients: ${detail.recipients.length}`);
console.log(`Fields: ${detail.fields.length}`);

Document Status Flow

DRAFT ──send()──→ PENDING ──all sign──→ COMPLETED
                      │
                      ├──reject()──→ REJECTED
                      └──cancel()──→ CANCELLED

Only DRAFT documents can be modified (add recipients, fields, change PDF).

Error Handling

Resources

• Documents API (SDK)
• Recipients API (SDK)
• Fields API (SDK)
• Field Types

Next Steps

For template-based workflows and direct signing links, see documenso-core-workflow-b.