---
updatedAt: 2026-02-16T18:00:38.000Z
agentTools:
  projectIndex: https://developers.pandadoc.com/llms.txt
---

# Signing Session Embed

## Overview

[**pandadoc-signing**](https://npmjs.com/pandadoc-signing) is a TypeScript library for embedding and interacting with PandaDoc Document Signing in your web applications.

### Use cases

* [Embedded Signing](https://developers.pandadoc.com/docs/embedded-signing)

For more information on embedded signing workflows, refer to the [Embedded Signing documentation](https://developers.pandadoc.com/docs/embedded-signing).

## Installation

Install using yarn:

```text
yarn add pandadoc-signing
```

or npm:

```text
npm install pandadoc-signing
```

## Usage

Import the library and create signing instance:

```typescript TypeScript
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](https://developers.pandadoc.com/reference/create-document-session) endpoint.

## API

**Signing** Class

**Constructor**

```typescript
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

```typescript
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

```typescript
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

```typescript
/**
 * 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

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

**DocumentEventPayload** Interface

```typescript
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

```typescript
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.