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.
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. You must have a Silver or Gold plan to use Embedded Signing in production mode. Otherwise, you can only use it in test mode.
2.
Create an API app (login required)
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.
Make a request to the API to create an embedded signature request.
Alternatively you can do it without using a template.
You just created an embedded signature request to two signers (Jack and Jill). When one of these users comes to your site, you will need to use the returned signature ids to fetch a temporary signature url that will be displayed in the iFrame (see below).
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 other signers still have not signed it. Upon success, it will return an Embedded object. The returned sign_url is what you will use as the url option when calling HelloSign.open() with our JavaScript library.
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.
To use it simply include the following code on your page.
<script type="text/javascript" src="https://s3.amazonaws.com/cdn.hellosign.com/public/js/hellosign-embedded.LATEST.min.js"></script>
HelloSign.init("CLIENT_ID");
HelloSign.open({
url: "SIGN_URL",
allowCancel: true,
messageListener: function(eventData) {
// do something
}
});JavaScript parameters for HelloSign.open():
| Parameter | Type | Description |
|---|---|---|
| url | String | Signature url you fetched via the API on your server.
Example:
"url": "https://app.hellosign.com/editor/embeddedSign? signature_id=78caf2a1d01cd39cea2bc1cbb340dac3& token=b6b8e7deaf8f0b95c029dca049356d4a2cf9710a" |
| redirectUrl (optional) |
String | Where the user will be redirected
after signing
Example: "redirectUrl": "http://my.site.com/redirect" |
| allowCancel (optional) |
Boolean | Whether to allow the user to cancel i.e. close the iFrame
without signing (default is true)
Example:
"allowCancel": false |
| messageListener (optional) |
Function | Called whenever the iFrame is messaging your page.
Example:
"messageListener" = function(eventData) {
if (eventData.event == HelloSign.EVENT_SIGNED) {
// Go to a signature confirmation page
document.location = "/signed?signature_id="
+ eventData["signature_id"];
}
} |
| debug (optional) |
Boolean | Enables debug output to console.log (default is false).
Example:
"debug": true |
| skipDomainVerification (optional) |
Boolean | Whether or not to skip the domain verification step (default is false). This will work only if the
Signature Request was created with test_mode=1.
Example:
"skipDomainVerification": true |
| container (optional) |
DOM Element | A DOM element from the page in which the iFrame will be inserted (default is document.body)
Example:
"container": document.getElementById('myHSContainer') |
| height (optional) |
Number |
The height of the iFrame in pixels. NOTE: Only applicable when a container is specified.
Example:
"height": 640 |
| uxVersion (optional) |
Integer |
The version of the embedded user experience to display to
signers. There are two versions: 1 - the original,
non-responsive signer page; and 2 - the new,
mobile-optimized signer page. NOTE: This option is only available to accounts who have accessed the API prior to November 14, 2015. It is provided as a means of deprecating the older user experience and allowing older integrators to opt into providing their users with the newer user experience. This option will be ignored if used by newer accounts.
Example:
"uxVersion": 2 |
| userCulture (optional) |
String |
The String that represents a supported language.
To see HelloSign's list of supported languages, check out our Languages page.
Example:
"userCulture": HelloSign.CULTURES.ZH_CN |
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.
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 easeier development:
HelloSign.open({
...
skipDomainVerification: true,
...
});
See the documentation for HelloSign.open() for more information.
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.
If a redirect url is specified, the iFrame will redirect users to it after they sign or decline to sign. Data from the EVENT_SIGNED event will be appended to the url query string.
Signature URLs are only valid for 60 minutes after embedded/sign_url has been called and expire as soon as they're accessed.
The embedded functionality can be used in conjunction with HelloSign Text Tags.
Here is the detail of all possible events the iFrame could send to the opening window:
| Event | Description | Data fields |
|---|---|---|
| HelloSign.EVENT_SIGNED |
The user has successfully signed the document.
IMPORTANT
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."
|
signature_id |
| HelloSign.EVENT_DECLINED | The user has declined to sign the document. | signature_id |
| HelloSign.EVENT_CANCELED | The user has canceled before the document was signed. | None |
| HelloSign.EVENT_ERROR | An error occurred and the document could not be signed. | description |
© 2017 
