--- name: documenso-core-workflow-a-4ea0c6e8e2a8 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.14.0 license: MIT author: Jeremy Longshore tags: - saas - documenso - workflow compatibility: Designed for Claude Code --- # 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 ```typescript 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: | Role | Behavior | |------|----------| | `SIGNER` | Must complete all assigned fields to finish | | `VIEWER` | Receives a copy but takes no action | | `APPROVER` | Must approve before signers can proceed | | `CC` | Receives a completed copy after all signatures | ```typescript // 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. ```typescript // 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. ```typescript // 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 ```typescript 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 ```typescript // 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 ```typescript // 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 | Error | HTTP | Cause | Solution | |-------|------|-------|----------| | Document not found | 404 | Invalid document ID | Verify ID with `findV0()` | | Recipient exists | 400 | Duplicate email on same doc | Update existing with `updateV0()` | | Invalid field position | 400 | pageX/pageY > 100 or < 0 | Use percentage values 0-100 | | Cannot modify sent doc | 400 | Document status is PENDING | Create new document or cancel first | | File too large | 413 | PDF exceeds plan limit | Compress PDF (plan limits vary) | ## Resources - [Documents API (SDK)](https://github.com/documenso/sdk-typescript/blob/main/docs/sdks/documents/README.md) - [Recipients API (SDK)](https://github.com/documenso/sdk-typescript/blob/main/docs/sdks/documentsrecipients/README.md) - [Fields API (SDK)](https://github.com/documenso/sdk-typescript/blob/main/docs/sdks/documentsfields/README.md) - [Field Types](https://docs.documenso.com/users/documents/fields) ## Next Steps For template-based workflows and direct signing links, see `documenso-core-workflow-b`. --- Source attribution: jeremylongshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/documenso-pack/skills/documenso-core-workflow-a/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2025 Jeremy Longshore Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: jeremylongshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/documenso-pack/skills/documenso-core-workflow-a/SKILL.md Attribution basis: Source repository record Fields of work: Product Management, Sales Roles: Customer Success Manager, Product Manager, Sales Operations Specialties: API, Design, Word Documents, Frontend, Git Tools: Documenso Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 3f680c30c07b0c628e664d7d20fdb37104bc6b1411ec476ba18131aba553ac93