Embed Formalingo document signing pages on any website using iframes or the JavaScript SDK.

Embedding Documents

Document signing pages can be embedded on external websites using an iframe or the JavaScript SDK. By default, document signing pages allow embedding from any domain (no whitelist required).

Quick Start — iFrame

<iframe
  src="https://www.formalingo.com/d/SIGNER_TOKEN"
  width="100%"
  height="800"
  frameborder="0"
  style="border: none;"
></iframe>

Replace SIGNER_TOKEN with the signer's token from the submission response.

Quick Start — JavaScript SDK

<div id="my-document"></div>
<script src="https://www.formalingo.com/embed.js"></script>
<script>
  Formalingo.createDocument({
    container: '#my-document',
    documentUrl: 'https://www.formalingo.com/d/SIGNER_TOKEN',
    onSigned: function(data) {
      console.log('Document signed!', data);
    },
    onReady: function(data) {
      console.log('Document loaded', data);
    }
  });
</script>

The SDK automatically resizes the iframe to fit the document content.

SDK Options Reference

Formalingo.createDocument(options)

Name	Type	Required	Description
container	string \| HTMLElement	optional	CSS selector or DOM element where the document will be rendered. Required.
documentUrl	string	optional	Full document signing URL (e.g. https://www.formalingo.com/d/TOKEN). Required.
height	number	optional	Initial iframe height in pixels. Default: 800.
autoResize	boolean	optional	Auto-resize iframe based on document content height. Default: true.
onReady	function(payload)	optional	Called when the document is fully loaded and interactive.
onSigned	function(payload)	optional	Called when the signer completes signing.
onFieldAnswered	function(payload)	optional	Called when a field value changes.
onError	function(payload)	optional	Called when a document error occurs (e.g. submission failure).
onHeightChange	function(payload)	optional	Called when the document content height changes.

The createDocument method returns an object with:

iframe — the HTMLIFrameElement reference
destroy() — removes the iframe and cleans up event listeners

postMessage Events

Embedded documents emit events to the parent window via postMessage. All events are prefixed with formalingo. and have this structure:

{
  "type": "formalingo.eventName",
  "payload": { ... }
}

Event Reference

Events

Name	Type	Required	Description
formalingo.documentLoaded	{ documentId, title }	optional	The document signing component has mounted.
formalingo.documentReady	{ documentId, title, fieldCount, signerRole }	optional	The document is fully loaded with all fields ready for interaction.
formalingo.fieldAnswered	{ documentId, fieldId, fieldType, completedFields, totalFields }	optional	A field value was changed. Does not include the field value for privacy.
formalingo.documentSigned	{ documentId, signerRole }	optional	The signer successfully completed signing.
formalingo.documentHeight	{ documentId, height }	optional	The document content height changed (used for auto-resize).
formalingo.documentError	{ documentId, error, code }	optional	An error occurred during the signing process.

Listening to Events Without the SDK

window.addEventListener('message', function(event) {
  var data = event.data;
  if (!data || !data.type || data.type.indexOf('formalingo.') !== 0) return;

  switch (data.type) {
    case 'formalingo.documentSigned':
      console.log('Document signed:', data.payload);
      break;
    case 'formalingo.fieldAnswered':
      console.log('Field completed:', data.payload.completedFields + '/' + data.payload.totalFields);
      break;
    case 'formalingo.documentHeight':
      document.querySelector('iframe').style.height = data.payload.height + 'px';
      break;
  }
});

Domain Whitelisting

By default, document signing pages can be embedded from any domain. To restrict embedding to specific domains, update the document settings:

curl -X PUT https://app.formalingo.com/api/v1/documents/DOC_ID \
  -H "Authorization: Bearer af_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "embed_allowed_domains": ["example.com", "*.company.io"]
    }
  }'

Set embed_allowed_domains to null to re-allow embedding from any domain (the default).

Troubleshooting

Issue	Cause	Fix
Document doesn't load in iframe	Domain blocked by whitelist	Check the document's `embed_allowed_domains` in settings
No auto-resize	SDK script not loaded	Verify the `embed.js` script tag loads correctly
Console error: `Refused to display in a frame`	CSP `frame-ancestors` restriction	Add your domain to the document's allowed embed domains
Signing events not firing	Using old SDK version	Ensure you're loading the latest `embed.js`

Embedding Documents

On this page