Skip to main content

Iframe or Embedded Signing

Embed/iframe the signing page in your own app.

If you need a simple open page that requires no customisation, where anyone can go and sign a document (and optionally confirm their email afterwards), try Legalesign's direct links. You can make these in the web app without code. They are embeddable too. Examples of direct links might be event registration, timesheets, liability waivers. Learn more about embeddable signing pages.

API​

If you need to customise the document, or require more functionality, then use the API.

Constraints​

Devices​

This relates to PDF based documents (not text/html based documents).

  • desktop contexts work well
  • mobile contexts work for simple documents (i.e. a signature, not complex forms)
  • mobile contexts where you have a complex form may not work well (especially for iphones) and we recommend you jump the user to a new browser window (you can hide this by removing signing page cruft and a redirect, see below).

While the last option is not seamless UX, it will ensure a reliable experience for your users. As far as we know, it is not possible to be confident about the size of the user's device from within an iframe window (in some or all iphones), which makes clean navigation around a complex form unreliable.

Signature standard​

A second warning, without some planning you may not meet the 'advanced' electronic signature standard.

Key tenets of the standard include a) your signatory must be in sole control of the signing process and b) they must be uniquely identifiable.

By receiving the signing link yourself you can now sign the document; sole control is lost.

A solution might be to add SMS validation for your recipient. Receipt of that sms text will be under your recipient's sole control and will uniquely identify them.

You will need to plan what controls are in place to ensure the signatory is identifiable and in sole control on your side to regain that 'advanced' standard. Learn more about the law on electronic signatures.

You will have followed the quickstart tutorial and successfully created/sent a document to be signed.

  1. Simply add the following attribute to your POST request that creates/sends a document (i.e. /api/v1/document/):
{return_signer_links: true}

  1. Read the BODY of the response and you will find a JSON object containing the signing links for each of your document recipients.

  2. Put the signing link within an iframe element.

Other helpful attributes​

  • To suppress all Legalesign emails, then in the POST to /api/v1/document/ set this attribute: {do_email: false}.

  • To redirect the user immediately after signing add this attribute: {redirect: yourUrl } (see more below).

  • To remove cruft from the signing page, add this querystring to the signing link: &hidenav=1&hidetext=1

Review all the send-document attributes here: Send Document API call

Safari factor​

If you expect safari users you may need to add a 'fix' with a small piece of javascript.

Safari's default security settings disallow iframe cookies. If you would like to handle this without user disruption, you will need to a) send us your root domain, and b) execute some javascript before the iframe loads - click here for the code (apologies for the jquery, you should be able to adjust as necessary). Within the js you will need to add some parameters to the URL that is queried. If this is unclear from the code example contact us for assistance.

Safari has made iframe increasingly difficult to use.

If you want to ensure iframe works in Safari you will need to use our new CNAME feature. This will put the signing pages in a subdomain of your main domain. This feature is still in beta, contact us if you wish to use it.

The best alternative is to jump users out to a new browser window, having set a redirect-after-signing URL on the document to bring them back following completion (see below).

Post-completion signals​

There are two ways to take control after a signing.

  • Set a redirect URL on your document when you create it. Legalesign will redirect the user to your URL after completing the document, or
  • use the javascript postMessage feature.

redirect url​

Simply add your redirect URL to the 'redirect' attribute of the POST request that creates the document (/api/v1/document/).

Since the redirect is per-document (not per-person) Legalesign will append a query string to your redirect URL that you can use to gather information about the document and signer states:

[your URL]?signer=[signer UID]&doc=[doc UID]&group=[group UID]&signer_state=[signer status]&doc_state=[doc state]

Click these links to see the reference table for document status and signer status.

postMessage​

A postMessage is a message signalled through javascript that you can receive in your parent frame. You can then use those messages to issue redirects or re-render the page as necessary.

After signing you will immediately receive one of three possible javascript postMessage messages: 'waiting’, 'signed’, 'rejected’.

If the document has been signed and you let the signing process continue and allow the download page to render in your iframe, you will also get the message 'download’ if the document download button is clicked.

You will get a 'waiting’ message if you have more than 1 signer and the document still needs other people to sign it.

For more information about postMessage see: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage.

If you intend to redirect the signer, be aware that he or she may briefly see a new page render (either the 'download' page or 'waiting for others' page) before your redirect using postMessage takes effect.

Next.​

After a signing you can download the final PDF document. We recommend using webhooks to do that. Learn more about webhooks. Check out the documentation for the API call to download a final PDF. Avoid pulling the download immediately after a signing event (using the post-signing signals above), the final PDF may not be ready. More reliably, listen for the webhook where the object is 'document' and the event is 'finalPdfCreated'.