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:

bash
npm install pdf-lib

typescript
// 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)

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

python
# 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)

bash
# 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.