Embedded Signing | HelloSign API Documentation
Embedded Signing

NOTE: This article is intended for HelloSign Embedded v2. As of August 2020, HelloSign Embedded v1 is no longer officially supported. If you are still using an older version of HelloSign Embedded, you can access a previous version of this article here.

Embedded signing allows you to have users sign signature requests on your site in an iFrame. The documentation below describes requirements and setup steps for the embedded signing flow. Take a look at our white labeling guide to learn more about customizing your app's embedded signing.

Preliminary

Before you start doing anything, make sure the following steps have been done:

1. Create an account if you don't already have one and retrieve your API key from the settings page. An Enterprise API plan is required to use Embedded Templates in production mode. Otherwise, you can only use it in test mode.

2. Create an API app (login required)

NOTE: The API app domain name specifies where the iFrame can be opened. Embedded Signing will only be possible on pages from this domain and its subdomains.

Try HelloSign Embedded

To get a feel for how our HelloSign Embedded library works, you can use our Embedded Testing Tool to quickly test any of our Embedded flows without having to write a single line of JavaScript.

You can request a sample document, or use the custom sign_url that you'll generate by following the walkthrough below.

Server Side

The very first step is to create an embedded signature request from your backend using our API and then fetch the associated url that will be used in the iFrame. Note that embedded signature requests use a different endpoint than ordinary signature requests.

You just created an embedded signature request with two signers (Jack and Jill). In the response above, both signers have been assigned a unique signature_id. When one of these users visits your site, you will need to use the HelloSign API generate a temporary sign_url using the signer's unique signature ID.

NOTE: This call will return HTTP 409 if the signature request has already been signed by this signer or—in the case of ordered signing—if the request cannot be signed yet because it is not their turn. Upon success, the endpoint will return an Embedded object. The returned sign_url is what will be opened using the HelloSign Embedded library.

Client Side

We provide a library that takes care of building and displaying the iFrame on your page for you. It should only take you a few lines of JavaScript code to make this functional.

If you are using a modern module bundler with npm, simply install hellosign-embedded.

npm install hellosign-embedded

If you are not using a modern module bunder like npm, HelloSign Embedded can be downloaded manually, compiled from source, or imported from our CDN.



In your app, import the hellosign-embedded module, instantiate a new client, then invoke open() with your signUrl and API client ID.

import HelloSign from 'hellosign-embedded';

const client = new HelloSign();

client.open(signUrl, {
  clientId: 'Your API client ID'
});

NOTE It's recommended that you add the following to your document's <head> to avoid unexpected behavior on small screens. <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0">

There are a number of options you can define as part of the second argument when calling open():

Name Type Description
locale string The locale code that will be used to determine which language the embedded request will be displayed in. For a list of HelloSign's supported languages, visit our Languages page. If no locale is specified HelloSign will attempt to determine the user's preferred language by their browser settings or fall back to English.

NOTE: Czech (CS_CZ) is only supported by Embedded Signing.
Example:
{
  locale: HelloSign.locales.ZH_CN
}
redirectTo string Where the user will be redirected after signing.
Example:
{
  redirectTo: 'http://example.com'
}
allowCancel boolean Whether the user should be able to close the iFrame without signing. Default: true.
Example:
{
  allowCancel: false
}
debug boolean Allows debug output to print to the console. Default: false.

For even more detailed debug output, run localStorage.debug = 'hellosign-embedded:*'; in your developer console and refresh the page.
Example:
{
  debug: true
}
skipDomainVerification boolean Whether or not to skip the domain verification step. Default: false.

NOTE: This will only be honored if the signature request was created with test_mode=1.
Example:
{
  skipDomainVerification: true
}
timeout number How long (in milliseconds) to wait for the HelloSign app to initialize before aborting. Default: 30000 (30 seconds).
Example:
{
  timeout: 10000
}
container HTMLElement By default HelloSign Embedded will be opened in a modal, but by specifying container you can choose a DOM element on the page in which the iFrame will be embedded.
Example:
{
  container: document.getElementById('sign-here')
}
What is the App Approval Process for Embedded Flows

In order to ensure that your integration adheres to eSignature regulations and best practices, we require a quick app review.

NOTE You will still be able to use your app in test mode until it gets approved. Only live/production activity requires approval.

1. Review our user identification requirements before adding Embedded Workflows into your website:

  • - User Profiles:
    If your platform has a user profile, your users must be authenticated on your website before they may create templates, sign documents, or request signatures.
    We also require that your users have previously confirmed ownership of the email address used to identify them to HelloSign. In practice, verifying email ownership means that when a user signs up for an account on your website, they should receive an email containing a unique link back to your site. When followed, your application can record the action, thus verifying the user's ownership of the email address. It is also important to recheck a user’s email if it’s allowed to be changed.
  • - Applications that do not have a user profile:
    If your application does not have a user profile concept, typically unique links are sent to the signer’s email address directly. The email usually includes a URL with a token that’s tied to the signer and signature request. When the signer clicks the link in the email, your app records the action, thus verifying the signer’s identity.
  • - In-Person signing:
    In-Person signing is a way of verifying your signer’s identity and allowing them to sign in person. We recommend creating a documented process such as uploading a picture of a driver's license or documenting a driver license number along with the signed document.
  • - If your workflow doesn’t fit, contact us and we will talk through it...

2. Email us at apisupport@hellosign.com to schedule an app review once your integration is complete and ready for production use.

3. Demonstrate your completed integration via screenshare (using a Google Hangout or Skype) by walking us through user account creation, email confirmation, and/or login on your website. We will also review your HelloSign integration as a whole to ensure proper functionality/to answer any questions that you may have. A review typically takes less than 30 minutes.

That's it! We’ll immediately approve your app (or make suggestions) after the review.

Additional notes
Domain restriction

When the iFrame is loaded, it will verify the domain of the parent window and ensure it matches the domain name of the API app specified by the client ID. If the domain does not match, the page won't be loaded.

You can disable domain restriction for easier development: 

client.open(signUrl, {
  // ...
  skipDomainVerification: true
});

This will allow you to use HelloSign Embedded on development domains, like localhost. See the documentation for HelloSign Embedded's open() method for more information.

HTTPS Required

The host page must be served over HTTPS. The HelloSign iFrame is also loaded over HTTPS, and due to browser security restrictions it will not be able to communicate with the parent window if it is not HTTPS. This communication is required to enable features such as iFrame callbacks and closing the iFrame.

To make development easier, the page will still load if the parent window is served over HTTP, however an alert will be displayed to notify you of this requirement. Switch to HTTPS to prevent this alert from being displayed.

Redirection

If a redirect url is specified, the iFrame will redirect users to it after they sign or decline to sign. Data from the sign event will be appended to the url query string.

Signature links

Signature URLs are only valid for 60 minutes after embedded/sign_url has been called and expire as soon as they're accessed.

It is best practice to wait until your signer hits the page before generating the sign_url so the link doesn't expire before the signer is ready. However, since the signature_id itself does not expire, a fresh sign_url can always be generated.

Text Tags

The embedded functionality can be used in conjunction with HelloSign Text Tags.

Events

There are a number of events that the HelloSign Embedded client may emit. To listen to these events, pass the event name and a callback function to on(). An string enumeration of available events can also be found under HelloSign.events. 

client.on('sign', (data) => {
  console.log('The document has been signed!');
  console.log('Signature ID: ' + data.signatureId);
});

Here are a list of possible events:

Event Description Data
ready Emitted when the HelloSign app embedded in the iFrame has initialized and the signature request is ready. 
{
  signatureId
}
sign Emitted when the user signs the signature request.
NOTE It may take up to a few minutes for the PDF to update and become available in its most-up-to-date form. Please be aware that while the PDF is still being updated, the /signature_request/files/[:signature_request_id] endpoint may return a HTTP status code of 409 with an error message of, "Files are still being processed. Please try again later." 
{
  signatureId
}
reassign Emitted when the user reassigns the signature request (if allow_reassign=1). 
{
  signatureId,
  name,
  email,
  reason
}
decline Emitted when the user declines the signature request (if allow_decline=1). 
{
  signatureId,
  reason
}
open Emitted when the HelloSign Embedded window has opened. 
{
  url,
  iFrameUrl
}
cancel Emitted when the signature request was canceled by the user by either pressing the close button or selecting "close" from the dropdown list.
finish Emitted when the user has finished the embedded signature request flow without cancelling. However, the user may have declined or reassigned the signature request.
message Emitted when HelloSign Embedded has received a cross-origin window message from the HelloSign app. 
{
  type,
  payload
}
close Emitted when the HelloSign Embedded window has closed.
error Emitted when the HelloSign app encounters an error. 
{
  signatureId,
  code
}