Signing Session Embed

Overview

pandadoc-signing is a TypeScript library for embedding and interacting with PandaDoc Document Signing in your web applications.

Use cases

Embedded Signing

For more information on embedded signing workflows, refer to the Embedded Signing documentation.

Installation

Install using yarn:

yarn add pandadoc-signing

or npm:

npm install pandadoc-signing

Usage

Import the library and create signing instance:

import { Signing } from "pandadoc-signing";

const signing = new Signing(
  "signing-container", // ID of the container element
  {
    width: 800,
    height: 600,
    sessionId: "Session ID from API",
  },
  {
    region: "com", // Optional: 'com' or 'eu'
  }
);

await signing.open();

You need to use Public API to generate a Session ID for PandaDoc document. See Create Document Session endpoint.

API

Signing Class

Constructor

constructor(id: string, configuration: SigningConfig, pdConfig: Partial<PDConfigModel>)

id: ID of the HTML element to replace with the signing iframe.
configuration: Signing configuration object.
pdConfig: PandaDoc configuration object.

Methods

open(options?): Opens the signing experience with the specified session ID. If sessionId is provided in the constructor configuration, the signing experience will automatically open once the iframe is ready and initialized.
close(): Closes the signing experience.
destroy(): Destroys the signing instance to free up resources and prevent memory leaks. After calling destroy(), the signing instance cannot be reused.
on(event, handler): Registers an event handler for signing session events. Returns the Signing instance for method chaining.
off(event, handler?): Removes an event handler. If no handler is specified, removes all handlers for the event. Returns the Signing instance for method chaining.
once(event, handler): Registers an event handler that will be called only once. Returns the Signing instance for method chaining.

Events

'document.loading': Triggered when the document loading starts
'document.loading.error': Triggered when the document loading fails
'document.protected': Triggered when the document is protected via sms verification
'document.attempts.limit.exceeded': Triggered when the document is protected via sms verification and the recipient has exceeded the maximum number of attempts
'document.not.found': Triggered when the document is not found
'document.loaded': Triggered when the document is loaded in the signing session
'document.rendered': Triggered when the document is rendered
'document.completed': Triggered when a recipient completes the document
'document.exception': Triggered if an error occurs during document finalization

SigningConfig Interface

interface SigningConfig {
  width?: number | string;
  height?: number | string;
  sessionId?: string;
  debugMode?: boolean;
}

width: Width of the signing iframe.
height: Height of the signing iframe.
sessionId: Document session ID that allows you to open the signing experience.
debugMode: Enable debug mode to log important steps and arguments.

PDConfigModel Interface

interface PDConfigModel {
  host?: string;
  region?: RegionType;
}

host: PandaDoc application host. Deprecated: Use region instead for better maintainability and future-proofing.
region: Region for the PandaDoc application. Defaults to 'com' if not specified. Available values: 'com' (app.pandadoc.com - global), 'eu' (app.pandadoc.eu - Europe).

Region Const

/**
 * Available regions for PandaDoc applications.
 */
export declare const Region: {
  readonly COM: "com";
  readonly EU: "eu";
};

COM: Use for global region (app.pandadoc.com).
EU: Use for EU region (app.pandadoc.eu).

SigningEventsMap Interface

interface SigningEventsMap extends Record<string, unknown> {
  "document.loaded": DocumentEventPayload;
  "document.completed": DocumentEventPayload;
  "document.exception": DocumentExceptionPayload;
}

DocumentEventPayload Interface

interface DocumentEventPayload {
  recipient?: {
    company: string;
    email: string;
    firstName: string | null;
    id: string;
    lastName: string | null;
  };
  uuid?: string;
  [key: string]: unknown;
}

recipient: Recipient information object.
uuid: Document ID.

DocumentExceptionPayload Interface

interface DocumentExceptionPayload {
  recipient?: {
    company: string;
    email: string;
    firstName: string | null;
    id: string;
    lastName: string | null;
  };
  uuid?: string;
  [key: string]: unknown;
}

recipient: Recipient information object.
uuid: Document ID.