Overview
Documenso supports five distinct recipient roles, each with different permissions and responsibilities. Choosing the right role ensures proper workflow execution and compliance with your signing requirements.
Available Roles
enum RecipientRole {
SIGNER
APPROVER
VIEWER
CC
ASSISTANT
}
Role Details
SIGNER
APPROVER
VIEWER
CC
ASSISTANT
Signer
The primary role for recipients who need to sign or fill fields in the document.Permissions:
- View the complete document
- Complete assigned fields (signature, date, text, etc.)
- Download the document
- Reject the document with a reason
Characteristics:
- Required for completion: Document cannot be completed until all signers finish
- Blocks workflow: In sequential signing, blocks next recipients until they complete
- Receives notifications: Gets initial email, reminders, and completion notification
- Tracked in audit log: All actions are logged with authentication details
- Certificate entry: Appears in signing certificate with signature details
Typical Fields:
- Signature
- Initials
- Name
- Email
- Date
- Text inputs
- Checkboxes
- Dropdowns
Use Cases:
- Employment contracts (employee signs)
- Sales agreements (client signs)
- NDAs (parties sign)
- Service agreements
- Consent forms
Signing Reason:
“I am signing this document as a party to the agreement”
Approver
For recipients who need to review and approve the document without formal signature.Permissions:
- View the complete document
- Complete assigned fields
- Approve or reject the document
- Download the document
Characteristics:
- Required for completion: Document cannot be completed until all approvers finish
- Blocks workflow: In sequential signing, blocks next recipients
- No signature required: Can use approval fields instead of signature
- Receives notifications: Gets all relevant emails
- Tracked in audit log: Approval/rejection is logged
- Certificate entry: Appears in certificate with approval details
Typical Fields:
- Checkbox (“I approve”)
- Date
- Name
- Comments/Text
- Radio buttons (Approve/Deny)
Use Cases:
- Manager approval workflows
- Budget approvals
- Policy acknowledgments
- Quality assurance sign-offs
- Compliance reviews
Signing Reason:
“I am approving this document in my capacity as an authorized approver”
Viewer
For recipients who need to see the document but don’t need to take action.Permissions:
- View the complete document
- Download the document
- Receive completion notification
Restrictions:
- Cannot complete any fields
- Cannot sign or approve
- Cannot reject the document
Characteristics:
- Not required for completion: Document can complete without viewer interaction
- Does not block workflow: Other recipients can proceed regardless
- Receives notifications: Gets document sent and completion emails
- Minimal audit trail: Only opening/viewing is tracked
- Certificate entry: May appear in certificate as viewer
Typical Fields:Use Cases:
- Legal counsel reviewing contracts
- Stakeholder notifications
- Record keeping recipients
- Observers in multi-party agreements
- Compliance documentation
Signing Reason:
“I am viewing this document for informational purposes”
CC (Carbon Copy)
For recipients who should receive a copy after the document is completed.Permissions:
- Receive completed document
- Download the signed document
- View the signing certificate
Restrictions:
- Cannot view document during signing process
- Cannot access document until completion
- Cannot interact with fields
- Cannot sign or approve
Characteristics:
- Not required for completion: Document completes without CC recipient action
- Does not block workflow: No impact on signing process
- Delayed notification: Only receives email after document is completed
- No audit trail during signing: Only receives completed document
- Certificate entry: May be listed as copy recipient
Typical Fields:
- None (receives copy only)
Use Cases:
- HR records after employee signs
- Accounting copies of invoices
- Legal department archives
- Management visibility
- Third-party notifications
Signing Reason:
“I am receiving a copy of this document for record-keeping purposes”
Assistant
For recipients who assist in the signing process on behalf of another party.Permissions:
- View the complete document
- Complete assigned fields
- Act on behalf of another party
- Download the document
Characteristics:
- Not required for completion: Document can complete without assistant action
- Does not block workflow: Optional participant
- Delegated authority: Acts on behalf of primary recipient
- Receives notifications: Gets relevant emails
- Tracked in audit log: Actions are logged with assistant identity
- Certificate entry: Appears with note of delegated authority
Typical Fields:
- Text fields (on behalf of)
- Name fields
- Date fields
- Checkboxes
Use Cases:
- Executive assistants signing for executives
- Authorized representatives
- Power of attorney scenarios
- Corporate secretary actions
- Delegated signing authority
Signing Reason:
“I am completing this document as an authorized assistant”
Role Comparison Matrix
| Feature | SIGNER | APPROVER | VIEWER | CC | ASSISTANT |
|---|
| View Document | ✓ | ✓ | ✓ | Only after completion | ✓ |
| Complete Fields | ✓ | ✓ | ✗ | ✗ | ✓ |
| Blocks Completion | ✓ | ✓ | ✗ | ✗ | ✗ |
| Blocks Sequential Flow | ✓ | ✓ | ✗ | ✗ | ✗ |
| Can Reject | ✓ | ✓ | ✗ | ✗ | Depends |
| Initial Notification | ✓ | ✓ | ✓ | ✗ | ✓ |
| Completion Notification | ✓ | ✓ | ✓ | ✓ | ✓ |
| Appears in Certificate | ✓ | ✓ | ✓ | ✓ | ✓ |
| Signature Field | ✓ | Optional | ✗ | ✗ | Optional |
| Authentication Required | Configurable | Configurable | Configurable | ✗ | Configurable |
Field Assignment by Role
Required Fields
Signers typically need:
- At least one SIGNATURE or INITIALS field
- DATE field (signing date)
- Optionally: NAME, EMAIL fields
Approvers typically need:
- CHECKBOX or RADIO field (approval selection)
- DATE field
- Optionally: TEXT field for comments
Viewers should have:
- No fields (read-only access)
CC Recipients should have:
- No fields (receive copy only)
Assistants may have:
- Any field type depending on delegation
- Often TEXT or NAME fields
Role Selection Guide
Decision Tree
Does the recipient need to sign?
├─ Yes → Is it a formal signature?
│ ├─ Yes → SIGNER
│ └─ No (just approval) → APPROVER
└─ No → Do they need to see it now?
├─ Yes → Can they take any action?
│ ├─ Yes (on behalf of others) → ASSISTANT
│ └─ No (just view) → VIEWER
└─ No (only after completion) → CC
Sequential Signing with Roles
In sequential signing mode, only certain roles block the workflow:
// Blocking roles (must complete before next recipient)
const blockingRoles = [RecipientRole.SIGNER, RecipientRole.APPROVER];
// Non-blocking roles (don't affect sequence)
const nonBlockingRoles = [RecipientRole.VIEWER, RecipientRole.CC, RecipientRole.ASSISTANT];
[
{ email: '[email protected]', role: 'SIGNER', signingOrder: 0 }, // Must sign first
{ email: '[email protected]', role: 'APPROVER', signingOrder: 1 }, // Then approves
{ email: '[email protected]', role: 'VIEWER', signingOrder: null }, // Can view anytime
{ email: '[email protected]', role: 'CC', signingOrder: null } // Gets copy at end
]
Authentication by Role
Different roles may require different authentication levels:
// High-security signing
{
role: RecipientRole.SIGNER,
authOptions: {
accessAuth: ['ACCOUNT', 'TWO_FACTOR_AUTH'],
actionAuth: ['PASSKEY']
}
}
// Standard approval
{
role: RecipientRole.APPROVER,
authOptions: {
accessAuth: ['ACCOUNT'],
actionAuth: ['PASSWORD']
}
}
// Open viewing
{
role: RecipientRole.VIEWER,
authOptions: {
accessAuth: [],
actionAuth: []
}
}
Best Practices
Role Assignment
-
Identify required actions
- Who must sign for legal validity?
- Who needs to approve for business process?
- Who needs visibility but no action?
-
Assign appropriate roles
- Use SIGNER for legally binding signatures
- Use APPROVER for internal approvals
- Use VIEWER for stakeholders
- Use CC for record recipients
-
Configure field assignments
- Ensure signers have signature fields
- Ensure approvers have approval fields
- Don’t assign fields to viewers or CC
-
Set up authentication
- Higher auth for signers/approvers
- Lower or no auth for viewers
- No auth needed for CC
Common Patterns
Employment Contract:
Purchase Order Approval:
[
{ email: '[email protected]', role: 'SIGNER', signingOrder: 0 },
{ email: '[email protected]', role: 'APPROVER', signingOrder: 1 },
{ email: '[email protected]', role: 'APPROVER', signingOrder: 2 },
{ email: '[email protected]', role: 'CC' }
]
API Examples
Create Document with Roles
POST /api/v1/documents
{
"recipients": [
{
"email": "[email protected]",
"name": "John Doe",
"role": "SIGNER"
},
{
"email": "[email protected]",
"name": "Jane Smith",
"role": "APPROVER"
},
{
"email": "[email protected]",
"name": "Bob Johnson",
"role": "VIEWER"
},
{
"email": "[email protected]",
"name": "Archive System",
"role": "CC"
}
]
}
Update Recipient Role
PUT /api/v1/documents/:id/recipients/:recipientId
{
"role": "APPROVER"
}
Recipient roles can only be changed while the document is in DRAFT status. Once sent, roles are locked to maintain audit trail integrity.
Webhook Events by Role
Different roles trigger different webhook events:
// SIGNER completed
{
"event": "DOCUMENT_SIGNED",
"data": {
"recipientRole": "SIGNER",
"recipientEmail": "[email protected]"
}
}
// APPROVER completed
{
"event": "DOCUMENT_SIGNED",
"data": {
"recipientRole": "APPROVER",
"recipientEmail": "[email protected]"
}
}
// VIEWER opened
{
"event": "DOCUMENT_OPENED",
"data": {
"recipientRole": "VIEWER",
"recipientEmail": "[email protected]"
}
}
CC recipients do not receive the document during the signing process. They only receive a copy after all required signers and approvers have completed their actions.
