documenso-core-workflow-a

name	documenso-core-workflow-a
description	Implement Documenso document creation and recipient management workflows. Use when creating documents, managing recipients, adding signature fields, or building signing workflows with Documenso. Trigger with phrases like "documenso document", "create document", "add recipient", "documenso signer", "signature field".
allowed-tools	Read, Write, Edit
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>

Documenso Core Workflow A: Document Creation & Recipients

Overview

Complete workflow for creating documents, managing recipients, and configuring signature fields in Documenso.

Prerequisites

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

Instructions

Step 1: Create Document with PDF Upload

import { Documenso } from "@documenso/sdk-typescript";
import { openAsBlob } from "node:fs";

const documenso = new Documenso({
  apiKey: process.env.DOCUMENSO_API_KEY ?? "",
});

async function createDocument(
  title: string,
  pdfPath: string
): Promise<string> {
  const pdfBlob = await openAsBlob(pdfPath);

  const document = await documenso.documents.createV0({
    title,
    file: pdfBlob,
  });

  console.log(`Created document: ${document.documentId}`);
  return document.documentId!;
}

Step 2: Add Multiple Recipients with Signing Order

interface RecipientInput {
  email: string;
  name: string;
  role: "SIGNER" | "VIEWER" | "APPROVER" | "CC";
  signingOrder?: number;
}

async function addRecipients(
  documentId: string,
  recipients: RecipientInput[]
): Promise<Map<string, string>> {
  const recipientMap = new Map<string, string>(); // email -> recipientId

  for (const recipient of recipients) {
    const result = await documenso.documentsRecipients.createV0({
      documentId,
      email: recipient.email,
      name: recipient.name,
      role: recipient.role,
      signingOrder: recipient.signingOrder,
    });

    recipientMap.set(recipient.email, result.recipientId!);
    console.log();
  }

   recipientMap;
}


 : [] = [
  { : , : , : , :  },
  { : , : , : , :  },
  { : , : , : , :  },
];

Step 3: Add Signature Fields

interface FieldInput {
  recipientId: string;
  type: "SIGNATURE" | "INITIALS" | "NAME" | "EMAIL" | "DATE" | "TEXT" | "CHECKBOX";
  page: number;
  x: number;
  y: number;
  width?: number;
  height?: number;
  required?: boolean;
  placeholder?: string;
}

async function addFields(
  documentId: string,
  fields: FieldInput[]
): Promise<string[]> {
  const fieldIds: string[] = [];

  for (const field of fields) {
    const result = await documenso.documentsFields.createV0({
      documentId,
      recipientId: field.recipientId,
      type: field.type,
      page: field.page,
      positionX: field.x,
      : field.,
      : field. ?? (field.),
      : field. ?? (field.),
    });

    fieldIds.(result.!);
    .();
  }

   fieldIds;
}

 ():  {
   : <, > = {
    : ,
    : ,
    : ,
    : ,
    : ,
    : ,
    : ,
  };
   widths[] ?? ;
}

 ():  {
   : <, > = {
    : ,
    : ,
    : ,
    : ,
    : ,
    : ,
    : ,
  };
   heights[] ?? ;
}

Step 4: Complete Document Creation Workflow

interface CreateSigningDocumentInput {
  title: string;
  pdfPath: string;
  recipients: Array<{
    email: string;
    name: string;
    role: "SIGNER" | "VIEWER" | "APPROVER" | "CC";
    signingOrder?: number;
    fields: Array<{
      type: "SIGNATURE" | "INITIALS" | "NAME" | "EMAIL" | "DATE" | "TEXT";
      page: number;
      x: number;
      y: number;
    }>;
  }>;
  sendImmediately?: boolean;
}

async function createSigningDocument(
  input: CreateSigningDocumentInput
): Promise<{ documentId: string; signingUrls: Map<string, string> }> {
  // Step 1: Create document with PDF
  const pdfBlob = await openAsBlob(input.);
    =  documenso..({
    : input.,
    : pdfBlob,
  });
   documentId = .!;

  
   recipientIds =  <, >();

   ( recipient  input.) {
     result =  documenso..({
      documentId,
      : recipient.,
      : recipient.,
      : recipient.,
      : recipient.,
    });
    recipientIds.(recipient., result.!);
  }

  
   ( recipient  input.) {
     recipientId = recipientIds.(recipient.)!;

     ( field  recipient.) {
       documenso..({
        documentId,
        recipientId,
        : field.,
        : field.,
        : field.,
        : field.,
        : (field.),
        : (field.),
      });
    }
  }

  
   (input.) {
     documenso..({ documentId });
    .();
  }

  
   signingUrls =  <, >();
   doc =  documenso..({ documentId });

   ( recipient  doc. ?? []) {
     (recipient.) {
      signingUrls.(recipient.!, recipient.);
    }
  }

   { documentId, signingUrls };
}


 result =  ({
  : ,
  : ,
  : [
    {
      : ,
      : ,
      : ,
      : ,
      : [
        { : , : , : , :  },
        { : , : , : , :  },
        { : , : , : , :  },
        { : , : , : , :  },
      ],
    },
    {
      : ,
      : ,
      : ,
      : ,
      : [
        { : , : , : , :  },
        { : , : , : , :  },
      ],
    },
  ],
  : ,
});

.();

Step 5: Update Recipients

async function updateRecipient(
  documentId: string,
  recipientId: string,
  updates: { email?: string; name?: string }
): Promise<void> {
  await documenso.documentsRecipients.updateV0({
    documentId,
    recipientId,
    ...updates,
  });
  console.log(`Updated recipient ${recipientId}`);
}

// Example: Correct email typo
await updateRecipient(documentId, recipientId, {
  email: "[e-mail]",
});

Step 6: Remove Recipients

async function removeRecipient(
  documentId: string,
  recipientId: string
): Promise<void> {
  await documenso.documentsRecipients.deleteV0({
    documentId,
    recipientId,
  });
  console.log(`Removed recipient ${recipientId}`);
}

Recipient Roles

Role	Description	Signs Document
SIGNER	Primary signer	Yes
APPROVER	Must approve before completion	Yes
VIEWER	Can view but not sign	No
CC	Receives copy when complete	No

Field Positioning Tips

• PDF coordinates start from bottom-left (0, 0)
• Standard letter size: 612 x 792 points
• Standard A4 size: 595 x 842 points
• Leave 50+ points margin from edges
• Signature fields: typically 200x60 points
• Text fields: typically 200x30 points

Output

• Created document with uploaded PDF
• Recipients added with signing order
• Signature fields positioned on pages
• Document sent for signing (optional)
• Signing URLs available for embedding

Error Handling

Error	Cause	Solution
Document not found	Invalid ID	Verify document exists
Recipient exists	Duplicate email	Update existing recipient
Invalid field position	Off-page coordinates	Check page dimensions
Cannot modify sent doc	Document already sent	Create new version
File too large	PDF exceeds limit	Compress or split PDF

Resources

• Documents API
• Recipients API
• Fields API

Next Steps

For template-based workflows, see documenso-core-workflow-b.