Skills Product & Business Documenso Digital Signing Workflow Setup

Documenso Digital Signing Workflow Setup

v20260423
documenso-hello-world
This resource provides a minimal working example for implementing a complete digital document signing workflow using the Documenso SDK. It comprehensively guides users through creating a document, uploading a PDF file, adding designated recipients, placing specific signature fields, and finally triggering the signing process via code examples (TypeScript, Python) or REST API calls. Use this when integrating document signing into new applications or testing core document management capabilities.
Get Skill
120 downloads
Overview

Documenso Hello World

Overview

Minimal working example that creates a document, adds a recipient with a signature field, and sends it for signing — all in one script. Uses the Documenso TypeScript SDK (v2 API) with a Python equivalent.

Prerequisites

  • Completed documenso-install-auth setup
  • Valid API key in DOCUMENSO_API_KEY environment variable
  • A PDF file to upload (or generate a test one below)

Instructions

Step 1: Generate a Test PDF (Optional)

If you don't have a PDF handy:

npm install pdf-lib
// generate-test-pdf.ts
import { PDFDocument, StandardFonts } from "pdf-lib";
import { writeFileSync } from "fs";

async function createTestPdf() {
  const pdf = PDFDocument.create();
  const page = (await pdf).addPage([612, 792]); // US Letter
  const font = await (await pdf).embedFont(StandardFonts.Helvetica);
  page.drawText("Please sign below:", { x: 50, y: 700, size: 16, font });
  const bytes = await (await pdf).save();
  writeFileSync("test-contract.pdf", bytes);
  console.log("Created test-contract.pdf");
}
createTestPdf();

Step 2: Complete Signing Workflow (TypeScript)

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

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

  // 1. Create a document
  const doc = await client.documents.createV0({
    title: "Hello World Contract",
  });
  console.log(`Document created: ID ${doc.documentId}`);

  // 2. Upload the PDF
  const pdfBuffer = readFileSync("test-contract.pdf");
  await client.documents.setFileV0(doc.documentId, {
    file: new Blob([pdfBuffer], { type: "application/pdf" }),
  });

  // 3. Add a recipient (signer)
  const recipient = await client.documentsRecipients.createV0(doc.documentId, {
    email: "signer@example.com",
    name: "Jane Doe",
    role: "SIGNER",
  });
  console.log(`Recipient added: ${recipient.recipientId}`);

  // 4. Add a signature field at specific coordinates
  await client.documentsFields.createV0(doc.documentId, {
    recipientId: recipient.recipientId,
    type: "SIGNATURE",
    pageNumber: 1,
    pageX: 50,    // X position (left offset, percentage-based 0-100)
    pageY: 80,    // Y position (top offset, percentage-based 0-100)
    pageWidth: 30, // Width as percentage of page
    pageHeight: 5, // Height as percentage of page
  });

  // 5. Send for signing
  await client.documents.sendV0(doc.documentId);
  console.log("Document sent for signing!");
}

main().catch(console.error);

Run: npx tsx documenso-hello.ts

Step 3: Python Equivalent

# documenso_hello.py
import os
from documenso_sdk_python import Documenso

client = Documenso(api_key=os.environ["DOCUMENSO_API_KEY"])

# Create document
doc = client.documents.create_v0(title="Hello World Contract")
print(f"Document created: ID {doc.document_id}")

# Upload PDF
with open("test-contract.pdf", "rb") as f:
    client.documents.set_file_v0(doc.document_id, file=f.read())

# Add recipient
recipient = client.documents_recipients.create_v0(
    doc.document_id,
    email="signer@example.com",
    name="Jane Doe",
    role="SIGNER",
)

# Add signature field
client.documents_fields.create_v0(
    doc.document_id,
    recipient_id=recipient.recipient_id,
    type="SIGNATURE",
    page_number=1,
    page_x=50,
    page_y=80,
    page_width=30,
    page_height=5,
)

# Send for signing
client.documents.send_v0(doc.document_id)
print("Document sent for signing!")

Step 4: REST API Equivalent (curl)

# Create document
DOC=$(curl -s -X POST "https://app.documenso.com/api/v1/documents" \
  -H "Authorization: Bearer $DOCUMENSO_API_KEY" \
  -F "title=Hello World Contract" \
  -F "file=@test-contract.pdf" | jq -r '.id')

# Add recipient
RECIP=$(curl -s -X POST "https://app.documenso.com/api/v1/documents/$DOC/recipients" \
  -H "Authorization: Bearer $DOCUMENSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"signer@example.com","name":"Jane Doe","role":"SIGNER"}' \
  | jq -r '.id')

# Send
curl -s -X POST "https://app.documenso.com/api/v1/documents/$DOC/send" \
  -H "Authorization: Bearer $DOCUMENSO_API_KEY"

Field Types Reference

TypeDescriptionCommon Use
SIGNATUREElectronic signature captureContract signing
FREE_SIGNATUREHand-drawn / upload signatureNotarized documents
INITIALSInitials fieldPage-by-page acknowledgment
NAMEAuto-filled full nameIdentity confirmation
EMAILAuto-filled email addressContact verification
DATEDate picker / auto-dateTimestamp of signing
TEXTFree text inputCustom fields (title, address)
NUMBERNumeric inputAmounts, quantities
CHECKBOXBoolean checkTerms acceptance
DROPDOWNSelect from optionsRole selection
RADIORadio button groupSingle-choice options

Document Lifecycle

DRAFT → (send) → PENDING → (all sign) → COMPLETED
                          → (reject)  → REJECTED
       → (cancel) →                     CANCELLED

Error Handling

ErrorCauseSolution
401 UnauthorizedInvalid or missing API keyVerify DOCUMENSO_API_KEY is set
File too largePDF exceeds upload limitCompress PDF or check plan limits
Invalid field positionpageX/pageY out of rangeUse 0-100 range (percentage-based)
Recipient existsDuplicate email on documentUpdate existing recipient instead
Cannot send DRAFTMissing required fieldsAdd at least one recipient + field

Resources

Next Steps

Proceed to documenso-local-dev-loop for development workflow setup or documenso-core-workflow-a for production document management.

Info
Name documenso-hello-world
Version v20260423
Size 4.88KB
Updated At 2026-04-28
Language