Embedded Signing

Overview

Embedded signing lets your users sign documents without leaving your application. Instead of receiving an email link, the signing experience appears directly within your product.

Integration Methods

1. JavaScript SDK (Recommended)

Install the SDK:

bash

npm install @ziasign/embed

Create a signing session and embed it:

typescript

import { ZiaSignEmbed } from "@ziasign/embed";

// 1. Create a signing session via your backend
const response = await fetch("/api/create-signing-session", {
  method: "POST",
  body: JSON.stringify({ documentId: "doc_abc123", signerEmail: "[email protected]" }),
});
const { signingUrl } = await response.json();

// 2. Mount the signing experience
const embed = new ZiaSignEmbed({
  container: document.getElementById("signing-container")!,
  url: signingUrl,
  // Customization options
  options: {
    showHeader: false,    // Hide the ZiaSign header
    showFooter: false,    // Hide the footer
    brandColor: "#4F46E5", // Your brand color
    locale: "en",
  },
});

// 3. Listen for events
embed.on("signed", (event) => {
  console.log("Document signed by:", event.signerEmail);
  // Update your UI
});

embed.on("declined", (event) => {
  console.log("Signer declined:", event.reason);
});

embed.on("completed", () => {
  console.log("All signers have signed");
  // Redirect or show success state
});

// 4. Mount
embed.mount();

2. Generate Signing URL (Server-Side)

Your backend requests a signing URL from the ZiaSign API:

python

# POST /documents/{id}/signing-sessions
response = ziasign_request("POST", f"/api/v1/documents/{doc_id}/signing-sessions", {
    "signerEmail": "[email protected]",
    "redirectUrl": "https://your-app.com/signing-complete",
    "expiresIn": 3600,  # URL valid for 1 hour
})

signing_url = response["signingUrl"]
# Return this URL to your frontend for embedding

3. iframe Embed

For simpler integrations, use an iframe directly:

html

<iframe
  src="SIGNING_URL_FROM_API"
  width="100%"
  height="800"
  style="border: none; border-radius: 12px;"
  allow="camera"
  title="Sign Document"
></iframe>

Note: The JavaScript SDK is preferred over raw iframes because it handles responsive resizing, cross-origin communication, and event callbacks.

Events

The SDK and iframe both emit events via postMessage:

Event	Data	Description
`ziasign:ready`	`{}`	Signing interface loaded
`ziasign:signed`	`{ signerEmail }`	Signer completed their fields
`ziasign:declined`	`{ reason }`	Signer declined to sign
`ziasign:completed`	`{ documentId }`	All signers completed
`ziasign:error`	`{ code, message }`	An error occurred

Redirect Mode

Instead of embedding, you can redirect users to ZiaSign and back:

Generate a signing URL with a redirectUrl parameter
Redirect your user to the signing URL
After signing, ZiaSign redirects back to your redirectUrl with the result

https://your-app.com/signing-complete?documentId=doc_abc123&status=completed&[email protected]

Frequently asked questions

Can I customize the embedded signing UI?

Yes. You can set your brand colors, logo, and hide ZiaSign branding (Business+ plans). The JavaScript SDK offers extensive customization options.

Is embedded signing secure?

Yes. Embedded signing uses the same security infrastructure as the standard experience: TLS 1.3, AES-256 encryption, and tamper-evident audit trails.

What plans support embedded signing?

Embedded signing is available on Pro and Max plans. White-label (ZiaSign branding removed) is available on negotiated business and enterprise agreements.