Authoring Embedding

Authoring embedding allows you to integrate Documenso’s document creation and field placement interface directly into your application. This enables users to create, edit, and configure documents without leaving your platform.

Authoring embedding is currently in development. This documentation describes the planned functionality based on the codebase schemas.

Overview

The authoring embed provides a full-featured document editor where users can:

Upload PDF documents
Place signature, text, date, and other field types
Configure recipient roles and settings
Set document options (timezone, date format, etc.)
Preview the signing experience

Configuration Options

Authoring embeds support granular feature control through the embed data schema:

interface AuthoringEmbedData {
  // Base customization
  darkModeDisabled?: boolean;
  css?: string;
  cssVars?: CssVariables;
  
  // External reference
  externalId?: string;
  
  // Feature flags
  features?: {
    allowConfigureSignatureTypes?: boolean;
    allowConfigureLanguage?: boolean;
    allowConfigureDateFormat?: boolean;
    allowConfigureTimezone?: boolean;
    allowConfigureRedirectUrl?: boolean;
    allowConfigureCommunication?: boolean;
  };
  
  // Edit mode
  onlyEditFields?: boolean; // Restrict to field placement only
}

Feature Flags

Signature Type Configuration

const embedData = {
  features: {
    allowConfigureSignatureTypes: true // Allow user to choose drawn/typed/uploaded signatures
  }
};

When enabled, users can configure:

Drawn signatures (signature pad)
Typed signatures (text-based)
Uploaded signature images

Language Configuration

const embedData = {
  features: {
    allowConfigureLanguage: true // Show language selector
  }
};

Allows users to set the document language for email notifications and signing interface.

Date Format Configuration

const embedData = {
  features: {
    allowConfigureDateFormat: true // Allow custom date format selection
  }
};

Lets users choose how date fields are formatted (MM/DD/YYYY, DD/MM/YYYY, etc.).

Timezone Configuration

const embedData = {
  features: {
    allowConfigureTimezone: true // Show timezone selector
  }
};

Enables timezone selection for date/time fields and audit trail.

Redirect URL Configuration

const embedData = {
  features: {
    allowConfigureRedirectUrl: true // Allow setting post-signing redirect
  }
};

Allows configuring where recipients are redirected after signing.

Communication Settings

const embedData = {
  features: {
    allowConfigureCommunication: false // Hide email notification settings
  }
};

Controls whether users can configure email sending and notifications.

Edit-Only Mode

Restrict the interface to field placement only, hiding document settings:

const embedData = {
  onlyEditFields: true, // Only show field editor
  features: {
    // All configuration options disabled in this mode
    allowConfigureSignatureTypes: false,
    allowConfigureLanguage: false,
    allowConfigureDateFormat: false,
    allowConfigureTimezone: false,
    allowConfigureRedirectUrl: false,
    allowConfigureCommunication: false
  }
};

Use cases:

Template field editing
Quick field updates
Simplified interface for non-technical users

External ID Tracking

Link documents to your internal systems:

const embedData = {
  externalId: 'order-12345' // Your internal reference
};

const hash = btoa(encodeURIComponent(JSON.stringify(embedData)));
const embedUrl = `https://app.documenso.com/embed/author/${documentId}#${hash}`;

The external ID is stored with the document and included in webhook events for cross-reference.

Basic Implementation

Full Authoring Interface

<!DOCTYPE html>
<html>
<head>
  <title>Create Document</title>
  <style>
    #authoring-embed {
      border: none;
      width: 100%;
      height: 100vh;
    }
  </style>
</head>
<body>
  <iframe
    id="authoring-embed"
    src="https://app.documenso.com/embed/author/new"
    allow="clipboard-read clipboard-write"
  ></iframe>

  <script>
    window.addEventListener('message', (event) => {
      if (event.origin !== 'https://app.documenso.com') return;
      
      switch (event.data.action) {
        case 'document-created':
          console.log('Document created:', event.data.data);
          // Save document ID to your database
          break;
        case 'document-sent':
          console.log('Document sent to recipients');
          // Update UI to show success
          break;
      }
    });
  </script>
</body>
</html>

Restricted Authoring

function createAuthoringEmbedUrl(documentId: string) {
  const embedData = {
    externalId: 'contract-789',
    features: {
      // Only allow field placement and signature config
      allowConfigureSignatureTypes: true,
      allowConfigureLanguage: false,
      allowConfigureDateFormat: false,
      allowConfigureTimezone: false,
      allowConfigureRedirectUrl: false,
      allowConfigureCommunication: false
    },
    // Custom branding
    cssVars: {
      primary: '#3b82f6',
      background: '#ffffff'
    }
  };

  const hash = btoa(encodeURIComponent(JSON.stringify(embedData)));
  return `https://app.documenso.com/embed/author/${documentId}#${hash}`;
}

React Component Example

import { useEffect, useState } from 'react';

interface AuthoringEmbedProps {
  documentId?: string; // Omit for new document
  externalId?: string;
  features?: {
    allowConfigureSignatureTypes?: boolean;
    allowConfigureLanguage?: boolean;
    allowConfigureDateFormat?: boolean;
    allowConfigureTimezone?: boolean;
    allowConfigureRedirectUrl?: boolean;
    allowConfigureCommunication?: boolean;
  };
  onlyEditFields?: boolean;
  onDocumentCreated?: (documentId: string) => void;
  onDocumentSent?: () => void;
}

export function DocumentAuthoringEmbed({
  documentId = 'new',
  externalId,
  features = {},
  onlyEditFields = false,
  onDocumentCreated,
  onDocumentSent
}: AuthoringEmbedProps) {
  const [embedUrl, setEmbedUrl] = useState<string>('');

  useEffect(() => {
    const embedData = {
      externalId,
      features,
      onlyEditFields
    };

    const hash = btoa(encodeURIComponent(JSON.stringify(embedData)));
    const url = `https://app.documenso.com/embed/author/${documentId}#${hash}`;
    setEmbedUrl(url);
  }, [documentId, externalId, features, onlyEditFields]);

  useEffect(() => {
    const handleMessage = (event: MessageEvent) => {
      if (event.origin !== 'https://app.documenso.com') return;

      switch (event.data.action) {
        case 'document-created':
          onDocumentCreated?.(event.data.data.documentId);
          break;
        case 'document-sent':
          onDocumentSent?.();
          break;
      }
    };

    window.addEventListener('message', handleMessage);
    return () => window.removeEventListener('message', handleMessage);
  }, [onDocumentCreated, onDocumentSent]);

  return (
    <iframe
      src={embedUrl}
      className="w-full h-screen border-0"
      allow="clipboard-read clipboard-write"
    />
  );
}

Usage

import { DocumentAuthoringEmbed } from './DocumentAuthoringEmbed';

function ContractCreator() {
  return (
    <DocumentAuthoringEmbed
      externalId="contract-order-456"
      features={{
        allowConfigureSignatureTypes: true,
        allowConfigureDateFormat: true,
        allowConfigureTimezone: true,
        // Hide advanced options
        allowConfigureLanguage: false,
        allowConfigureRedirectUrl: false,
        allowConfigureCommunication: false
      }}
      onDocumentCreated={(documentId) => {
        console.log('Document created:', documentId);
        // Save to your database
      }}
      onDocumentSent={() => {
        console.log('Document sent!');
        // Show success message
      }}
    />
  );
}

Authoring Events

The authoring embed sends these events:

type AuthoringEvent =
  | { action: 'authoring-ready'; data: null }
  | { action: 'document-created'; data: {
      documentId: string;
      externalId?: string;
    }}
  | { action: 'document-updated'; data: {
      documentId: string;
    }}
  | { action: 'document-sent'; data: {
      documentId: string;
      recipientCount: number;
    }}
  | { action: 'field-added'; data: {
      fieldId: string;
      fieldType: string;
    }}
  | { action: 'field-removed'; data: {
      fieldId: string;
    }}
  | { action: 'authoring-error'; data: {
      message: string;
    }};

Use Cases

Template Editor

// Embed template editing with minimal UI
const templateEditorConfig = {
  onlyEditFields: true,
  features: {
    allowConfigureSignatureTypes: true
  }
};

Customer Onboarding Portal

// Let customers create their own contracts
const customerPortalConfig = {
  externalId: `customer-${customerId}`,
  features: {
    allowConfigureSignatureTypes: true,
    allowConfigureDateFormat: true,
    allowConfigureTimezone: true,
    allowConfigureLanguage: true,
    // Hide redirect and communication for simplicity
    allowConfigureRedirectUrl: false,
    allowConfigureCommunication: false
  }
};

Admin Dashboard

// Full featured authoring for admins
const adminConfig = {
  externalId: `admin-${adminId}-${timestamp}`,
  features: {
    allowConfigureSignatureTypes: true,
    allowConfigureLanguage: true,
    allowConfigureDateFormat: true,
    allowConfigureTimezone: true,
    allowConfigureRedirectUrl: true,
    allowConfigureCommunication: true
  }
};

White-Label Customization

Customize the authoring interface appearance:

const embedData = {
  css: `
    /* Hide Documenso branding */
    .branding-logo { display: none; }
    
    /* Custom button styles */
    .btn-primary {
      background: linear-gradient(to right, #667eea, #764ba2);
    }
  `,
  cssVars: {
    primary: '#667eea',
    secondary: '#764ba2',
    background: '#f9fafb',
    foreground: '#111827',
    border: '#e5e7eb',
    radius: '0.5rem'
  }
};

See CSS Variables for complete customization options.

Limitations

Authoring embeds require Enterprise plan
File uploads limited by your plan’s document limits
Some features may be restricted based on subscription tier
Custom branding requires embedSigningWhiteLabel flag

Next Steps

Direct Links

Embed the signing experience

CSS Variables

Customize appearance and branding

​Overview

​Configuration Options

​Feature Flags

​Signature Type Configuration

​Language Configuration

​Date Format Configuration

​Timezone Configuration

​Redirect URL Configuration

​Communication Settings

​Edit-Only Mode

​External ID Tracking

​Basic Implementation

​Full Authoring Interface

​Restricted Authoring

​React Component Example

​Usage

​Authoring Events

​Use Cases

​Template Editor

​Customer Onboarding Portal

​Admin Dashboard

​White-Label Customization

​Limitations

​Next Steps

Direct Links

CSS Variables

Overview

Configuration Options

Feature Flags

Signature Type Configuration

Language Configuration

Date Format Configuration

Timezone Configuration

Redirect URL Configuration

Communication Settings

Edit-Only Mode

External ID Tracking

Basic Implementation

Full Authoring Interface

Restricted Authoring

React Component Example

Usage

Authoring Events

Use Cases

Template Editor

Customer Onboarding Portal

Admin Dashboard

White-Label Customization

Limitations

Next Steps