Embedded signing

Give your users the ability to sign documents directly in your product. Formable returns a short-lived signing URL that you load in an iframe — no email round-trip required. This walkthrough covers the full embedded signing flow: create a signature request on your server, embed the signing experience on the client, detect completion, and download the signed PDF.

Need a shorter path first? Complete the quickstart, then return here for the full integration pattern.

Prefer email delivery instead of an iframe? See Non-embedded signing.

Prerequisites

Before you begin:

Create an organization and API key in Settings.
Upload a template, place at least one required signature field, and assign it a signer role — see the Embedded templates walkthrough.
Call the Formable API from your backend only. Never expose your API key in the browser.

Overview

Create an embedded signature request

Start a request from a template with one or more signers (each with a role).

Generate a signing URL

Mint a short-lived URL for a signer’s recipientSignatureId just before they are ready.

Embed the URL in an iframe

Load the signing experience inside your product.

Detect completion and download

Listen for webhooks or poll status, then fetch the signed PDF.

Server side

Create the signature request and signing URL on your backend, then pass only the URL to the client.

1. Create an embedded signature request

Start from a template you’ve already prepared. An embedded signature request needs:

templateId — which document to send
signers — who will sign (email, name, and role for every role used by required fields)

sender is optional. When omitted, Formable uses the API key organization owner.

curl --request POST \
  --url https://api.formabledocs.com/v1/signature-requests/embedded \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "templateId": "abc123xyz",
    "signers": [
      { "email": "signer@example.com", "name": "Jane Doe", "role": "Client" }
    ],
    "sender": { "email": "you@yourcompany.com", "name": "Your Company" },
    "testMode": true
  }'

Response

{
  "signatureRequestId": "sr_456def",
  "templateId": "abc123xyz",
  "signers": [
    {
      "email": "signer@example.com",
      "name": "Jane Doe",
      "recipientSignatureId": "rsig_789ghi"
    }
  ],
  "sender": { "email": "you@yourcompany.com", "name": "Your Company" },
  "status": "Created",
  "testMode": true
}

Save the signatureRequestId for status and download. Save each signer’s recipientSignatureId to mint their signing URL.

Prefill fields

Templates can include fields beyond the signature — company name, dates, checkboxes, and so on. Pass a fields array to set values before the signer opens the document. Each entry sets a value on a fieldId from the template.

{
  "templateId": "abc123xyz",
  "signers": [
    { "email": "signer@example.com", "name": "Jane Doe", "role": "Client" }
  ],
  "sender": { "email": "you@yourcompany.com", "name": "Your Company" },
  "fields": [
    { "fieldId": "field_company_name", "value": "Acme Corporation" },
    { "fieldId": "field_effective_date", "value": "2024-02-01" }
  ],
  "testMode": true
}

Field IDs come from the template. Open the template’s editor URL to place fields and copy their IDs. A fieldId that doesn’t exist on the template returns a 400.

Test mode

Set testMode: true while integrating so the request doesn’t count toward billing. Test mode documents are watermarked and are not legally binding.

2. Generate a signing URL

A signing URL opens the signing experience for one recipient. Create it with that signer’s recipientSignatureId. It expires one hour after creation, so generate it right before you show it to the signer.

curl --request POST \
  --url https://api.formabledocs.com/v1/recipient-signatures/rsig_789ghi/url \
  --header "Authorization: Bearer $TOKEN"

Response

{
  "signingUrl": "https://app.formabledocs.com/sign/embedded/xyz789abc",
  "expiresAt": "2024-01-16T10:30:00.000Z"
}

Creating a signing URL for an already completed request returns 409.

Client side

Embed the signingUrl in an iframe so the signer can complete the document without leaving your product.

<iframe
  src="https://app.formabledocs.com/sign/embedded/xyz789abc"
  width="100%"
  height="800"
  allow="fullscreen"
  style="border: none;"
></iframe>

Request the URL from your backend and pass it to the page just before rendering:

function SigningFrame({ recipientSignatureId }) {
  const [signingUrl, setSigningUrl] = useState(null);

  useEffect(() => {
    fetch(`/api/formable/signing-url?recipientSignatureId=${recipientSignatureId}`)
      .then((res) => res.json())
      .then((data) => setSigningUrl(data.signingUrl));
  }, [recipientSignatureId]);

  if (!signingUrl) return <p>Loading…</p>;

  return (
    <iframe
      src={signingUrl}
      width="100%"
      height="800"
      allow="fullscreen"
      style={{ border: "none" }}
      title="Sign document"
    />
  );
}

<iframe
  src="{{ signingUrl }}"
  width="100%"
  height="800"
  allow="fullscreen"
  style="border: none;"
></iframe>

Never call the Formable API with your token from the browser. Generate the signing URL on your server and hand only the resulting URL to the client.

Give the iframe enough height (around 800px) so signers don’t have to scroll within a small frame. Regenerate the URL if the signer returns after it has expired.

Signing experience

Once the iframe loads, the signer walks through required fields on the document. Click Start to begin. Required fields are highlighted so the signer knows where to act.

Embedded signing view showing document.docx with a Sign here field on the Customer line, a Required callout, and a Start button — The signing experience with a required Signature field highlighted. Click Start to begin.

When the signer reaches a Signature field, they can Draw, Type, or use a Saved signature. They must agree to the terms and conditions before confirming.

Signature modal over the document with Draw, Type, and Saved tabs, a drawn signature, consent checkbox, and Confirm button — The signature modal with Draw selected. Signers can also type a signature or reuse a saved one.

After all required fields are complete, the signer reviews the document and clicks Finish. That completes the signature request and fires onSigningComplete to the parent window.

Embedded signing view with a completed Customer signature and a Finish button — Review step after the signature is placed. Click Finish to complete the request.

Detect completion

When the signer finishes, the signature request status becomes Completed. You have four ways to learn that:

Listen for iframe postMessages

When signing finishes inside the embedded iframe, Formable posts a message to the parent window. Use this to close the iframe or update your UI immediately:

window.addEventListener("message", (event) => {
  if (event.origin !== "https://app.formabledocs.com") return;
  if (!event.data || typeof event.data !== "object") return;

  switch (event.data.type) {
    case "onSigningComplete":
      // Signer finished — close the iframe or show a success state
      break;
    case "onSigningError":
      // Signing failed to complete — show an error or retry
      break;
  }
});

Message `type`	When it fires
`onSigningComplete`	The signer successfully completed the document.
`onSigningError`	Signing could not be completed from the iframe.

Always check event.origin. Treat these as client UX signals — confirm completion with a webhook or API poll before downloading the signed PDF.

Listen for the document_completed webhook

Configure a webhook endpoint and handle the document_completed event. Formable pushes this once the signed PDF is ready, so you can download without polling. Do not use document_signed alone — that fires when a signer finishes, before the completed file is available.

{
  "event": {
    "event_type": "document_completed",
    "event_category": "signing"
  },
  "signing": {
    "signature_request_id": "sr_456def"
  }
}

Poll the signature request status

Fetch the signature request and check status. It moves from Created to Completed. The response also includes signers (with recipientSignatureId) and envelope fields.

curl --request GET \
  --url https://api.formabledocs.com/v1/signature-requests/sr_456def \
  --header "Authorization: Bearer $TOKEN"

Read the event stream

Fetch signature request events for a chronological history of what happened.

curl --request GET \
  --url https://api.formabledocs.com/v1/signature-requests/sr_456def/events \
  --header "Authorization: Bearer $TOKEN"

Use iframe postMessage for immediate UI updates, and prefer the document_completed webhook as the source of truth before downloading. Use List signature requests with updatedSince, or the event stream, to reconcile anything you missed.

Download the signed PDF

Once status is Completed, fetch a temporary download URL for the signed PDF (the signed envelope).

curl --request GET \
  --url https://api.formabledocs.com/v1/signature-requests/sr_456def/signed-envelope \
  --header "Authorization: Bearer $TOKEN"

Response

{
  "signedEnvelopePresignedUrl": "https://s3.amazonaws.com/bucket/signed-envelope.pdf?..."
}

Open or download that URL promptly — it is a short-lived presigned link. The signed PDF includes an audit trail with timestamps, actors, and IP addresses for each step.

Formable audit trail page for document.docx with Envelope ID, Completed status, and a Document History of Created, Sent, Signed, and Completed events — Audit trail appended to the signed PDF, showing Created, Sent, Signed, and Completed events.

Requesting the signed envelope before signing is complete returns 409 with "Envelope has not been signed yet".

Next steps

Embedded templates

Upload documents and place signature and form fields.

Webhooks

Get notified when a document is viewed or signed.

Redlining

Negotiate a DOCX contract before signing.

API reference

Full endpoint docs for signature requests.

Getting Started

Walkthroughs

SDKs

Migrations

Webhooks

Prerequisites

Overview

Server side

1. Create an embedded signature request

Prefill fields

Test mode

2. Generate a signing URL

Client side

Signing experience

Detect completion

Download the signed PDF

Next steps

Embedded templates

Webhooks

Redlining

API reference

​Prerequisites

​Overview

​Server side

​1. Create an embedded signature request

​Prefill fields

​Test mode

​2. Generate a signing URL

​Client side

​Signing experience

​Detect completion

​Download the signed PDF

​Next steps

Embedded templates

Webhooks

Redlining

API reference

Prerequisites

Overview

Server side

1. Create an embedded signature request

Prefill fields

Test mode

2. Generate a signing URL

Client side

Signing experience

Detect completion

Download the signed PDF

Next steps