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

Type	Description	Common Use
SIGNATURE	Electronic signature capture	Contract signing
FREE_SIGNATURE	Hand-drawn / upload signature	Notarized documents
INITIALS	Initials field	Page-by-page acknowledgment
NAME	Auto-filled full name	Identity confirmation
EMAIL	Auto-filled email address	Contact verification
DATE	Date picker / auto-date	Timestamp of signing
TEXT	Free text input	Custom fields (title, address)
NUMBER	Numeric input	Amounts, quantities
CHECKBOX	Boolean check	Terms acceptance
DROPDOWN	Select from options	Role selection
RADIO	Radio button group	Single-choice options

Document Lifecycle

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

Error Handling

Error	Cause	Solution
401 Unauthorized	Invalid or missing API key	Verify DOCUMENSO_API_KEY is set
File too large	PDF exceeds upload limit	Compress PDF or check plan limits
Invalid field position	pageX/pageY out of range	Use 0-100 range (percentage-based)
Recipient exists	Duplicate email on document	Update existing recipient instead
Cannot send DRAFT	Missing required fields	Add at least one recipient + field

Resources

• Documenso Getting Started
• TypeScript SDK Docs
• API Reference (OpenAPI)
• Field Types Documentation

Next Steps

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