Embedded Requesting | HelloSign API Documentation
Embedded Requesting

NOTE: This article is intended for HelloSign Embedded v1 which is not officially supported after August 2020. You can access the new version of this article here. If you need help migrating from v1 to v2, please refer to our migration guide.

Embedded requesting allows you to have users create and send signature requests on your site in an iFrame. The documentation below describes requirements and setup steps for the embedded requesting flow.

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 Requesting 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 edit_url that you'll generate by following the walkthrough below.

Server Side

The very first step is to create a draft signature request from your backend using our API. You must decide what you want to happen after the signature request is sent by your user. By default, HelloSign will send an email to the signers and ask them to come to hellosign.com to sign and complete the document(s):

Alternatively, you can use embedded requesting in conjunction with embedded signing by specifying the 'is_for_embedded_signing' parameter. This will instruct HelloSign to NOT email the signers and will allow you to decide when and how to display the embedded signing iFrame on your site.

In this scenario, you will need to retrieve the signature url after the request has been sent using embedded/sign_url. See the embedded signing walkthrough to learn how to construct the embedded signing page from that point on.

NOTE If you'd like to specify the signers and CCs during this step (rather than let the user specify them when they edit and send the signature request), you can include the 'signers' and 'cc_email_addresses' parameters. See the unclaimed_draft/create_embedded documentation for more info.

Now that you've created an embedded signature request for jolene@example.com to edit and send out, you need to grab the claim_url from the JSON response. You will need to pass this claim_url to the Client Side to use in HelloSign.open().

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.

To use it simply include the following code on your page.

<script nonce="NpDLkMHNuPknsonW0HNIuzYa" type="text/javascript" src="https://cdn.hellosign.com/public/js/hellosign-embedded.LATEST.min.js"></script>
HelloSign.init("CLIENT_ID");
HelloSign.open({
    url: "CLAIM_URL",
    allowCancel: true,
    messageListener: function(eventData) {
        // do something
    }
});

JavaScript parameters for HelloSign.open():

Parameter Type Description
url String Claim url you fetched via the API on your server.
Example:
"url": "https://app.hellosign.com/send/embeddedRequest?tsm_group_type=request_signature&root_snapshot_guids[]=2f77ee229d099c952d4a5332ab16dde30aada097&snapshot_access_guids[]=22b53f76&guid=4d05a969dbff8d3b139b0a3dd7a57243c5f3e036"
requester
(optional)		 String The email of the person issuing a signature request. Required for allowing 'Me + Others' requests.
Example:
"requester": "requester@example.com"
redirectUrl
(optional)		 String Where the user will be redirected after sending the signature request
Example:
"redirectUrl": "http://my.site.com/redirect"
allowCancel
(optional)		 Boolean Whether to allow the user to cancel i.e. close the iFrame without finishing the request (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_SENT) {
        // Go to a signature request sent confirmation page
        document.location = "/sent?signature_request_id=" 
					+ eventData["signature_request_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
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 easeier development: 

HelloSign.open({
  // ...
  skipDomainVerification: true
});

See the documentation for HelloSign.open() 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 send the document(s). Data from the EVENT_SENT event will be appended to the url query string.

Text Tags

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

Events

Here is the detail of all possible events the iFrame could send to the opening window:

Event Description Data fields
HelloSign.EVENT_SENT The user has successfully sent the document.
signature_request_id
signature_request_info
  • title
  • message
  • signatures
  • cc_email_addresses
HelloSign.EVENT_CANCELED The user has canceled before the document was sent.
HelloSign.EVENT_ERROR An error occurred and the document could not be sent. description