Embedded Templates | HelloSign API Documentation
Embedded Templates

NOTE: This article is intended for HelloSign Embedded v2. As of May 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 templates allow your users to create and edit templates on your site in an iFrame. Templates are used to share frequently-used documents and send them for signatures.

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

Creating a template

Allowing your site users to create a template involves first creating a template draft. This draft will be displayed on your site in an embedded iFrame, allowing the user to edit and finalize the template. Note that templates created via the embedded template process will only be accessible through the API.

1. Create a template draft by POSTing an API request to https://api.hellosign.com/v3/template/create_embedded_draft with the following parameters:

2. Retrieve the edit_url from the API response, which will be a JSON object like the one below. Be sure to also store the template_id for future referencing of the completed template. skip_signer_roles=1 is an optional parameter you can append which will not allow the person editing the template to add or change the signer roles that have already been defined.

Note: skip_signer_roles will be deprecated in May 2020 and skipping the signer role screen will become the default behavior. To enforce showing the signer role screen, set force_signer_roles=1.

{
  "template" : {
    "template_id" : "abcdef1234567890abcdef1234567890",
    "edit_url" : "https://app.hellosign.com/editor/...",
    "expires_at" : "123456790"
  }
}

3. Set up the frontend. If you are using a modern module bundler with npm, simply install hellosign-embedded. Otherwise, HelloSign Embedded can be downloaded manually, compiled from source, or imported from our CDN.

npm install hellosign-embedded

4. Create a new HelloSign Embedded client. Import the hellosign-embedded module instantiate a new client.

import HelloSign from 'hellosign-embedded';

const client = new HelloSign({
  clientId: 'Your API client ID'
});

5. Open HelloSign Embedded. Call client.open() with the editUrl you got from a previous step.

client.open(editUrl);

6. The embedded iFrame will be displayed and the user will be walked through the process of editing and finalizing the template for future use.

Pre-defined merge fields

By creating a template draft with merge fields, you are essentially telling your users, "The app can supply this information for you when you use the completed template to send a signature request."

This can be useful if, for example, your app stores contact information. If a user sends a signature request to one of the contacts in your system, you can pre-populate the signature request with contact details prior to sending. It's necessary to provide these details as 'merge fields' during the template creation because it indicates where the data should be placed within the document when sending the signature request.

As explained in the Creating a template section, merge fields are specified during the template draft creation API request as a JSON array. Each merge field must have a unique name, and this is enforced by the API.

When the user is presented with the template draft editor, they are allowed to place these merge fields in the document. Merge fields appear to the user as standard Textbox and Checkbox fields. When one of these fields is placed on the document, the context menu will display the app as an option for the data source (in the "Who fills this out?" dropdown list), and the names of any pre-defined merge fields are listed in the dropdown underneath "What text goes here?".

Once the template is saved, the data to populate these merge fields can be specified in the API call to create a signature request. This not only saves the user time, but also ensures better data accuracy. To populate the merge fields, simply execute a /signature_request/send_with_template and use the custom_fields parameter, or supply the same parameter when creating an embedded draft for previewing (see Previewing a signature request below).

Editing a template

Once a template has been created, you can also open an embedded iFrame that allows your site users to edit it. Note that only templates created via the embedded template process are available to be edited with this endpoint.

1. Make a GET or POST request to https://api.hellosign.com/v3/embedded/edit_url/[:template_id]. A POST request is required if merge_fields or cc_roles are being changed.

2. merge_fields is an optional parameter which can be supplied here to edit which available fields the user editing the template has access to place. Fields already placed on the document will not be removed, but will default to empty if no custom field is supplied for them.
cc_roles is an optional parameter that can also be supplied to update the CC roles for the template.

skip_signer_roles=1 is an optional parameter you can append which will not allow the person editing the template to add or change the signer roles that have already been defined.
skip_subject_message=1 is an optional parameter you can append which will not allow the person editing the template to change the subject and/or message which has already been provided.

Note: skip_signer_roles and skip_subject_message will be deprecated in May 2020. Skipping the signer role and subject message screens will become the default behavior. To enforce showing these screens, set force_signer_roles=1 and/or force_subject_message=1.

3. Retrieve the edit_url from the API response, which will be a JSON object like the one below. This URL will be used in the same manner as the edit_url retrieved for the template draft creation.

{
  "embedded" : {
    "edit_url" : "https://app.hellosign.com/editor/...",
    "expires_at" : "123456790"
  }
}

4. Set up the frontend. If you are using a modern module bundler with npm, simply install hellosign-embedded. Otherwise, HelloSign Embedded can be downloaded manually, compiled from source, or imported from our CDN.

npm install hellosign-embedded

5. Create a new HelloSign Embedded client. Import the hellosign-embedded module instantiate a new client.

import HelloSign from 'hellosign-embedded';

const client = new HelloSign({
  clientId: 'Your API client ID'
});

6. Open HelloSign Embedded. Call client.open() with the editUrl you got from a previous step.

client.open(editUrl);

7. The embedded iFrame will be displayed and the user will be walked through the process of editing and finalizing the template.

Previewing a signature request

When your site user needs to send a signature request based on a template, you will need to create an embedded signature request draft. This draft can be opened in an embedded iFrame to allow the user to preview the request prior to sending. Creating the signature request draft for previewing is also a perfect opportunity to populate any pre-defined merge fields that might have been added by the user during the template creation process.

1. Create the embedded template draft by making a POST request to https://api.hellosign.com/v3/unclaimed_draft/create_embedded_with_template with the following parameters:

2. Retrieve the claim_url from the API response, which will be a JSON object like the one below. This URL will be used in the same manner as the edit_url for template creation and editing to display the preview to the user.

{
  "unclaimed_draft": {
    "claim_url": "https://app.hellosign.com/editor/embeddedRequest?cached_params_token=2f42ca09a50345af9ef8720f5b001f27",
    "signing_redirect_url": null,
    "test_mode": true,
    "signature_request_id": "340e9843ac552b5170ee9c374d67e312f53ca129",
    "requesting_redirect_url": null
  }
}

3. Set up the frontend. If you are using a modern module bundler with npm, simply install hellosign-embedded. Otherwise, HelloSign Embedded can be downloaded manually, compiled from source, or imported from our CDN.

npm install hellosign-embedded

4. Create a new HelloSign Embedded client. Import the hellosign-embedded module instantiate a new client.

import HelloSign from 'hellosign-embedded';

const client = new HelloSign({
  clientId: 'Your API client ID'
});

5. Open HelloSign Embedded. Call client.open() with the claimUrl you got from a previous step.

client.open(claimUrl);

6. The embedded iFrame will be displayed and the user will be given an opportunity to preview and make edits to the signature request prior to sending. Any custom_fields parameters supplied to the draft creation API request will be added to the document as well and these fields can also be edited and moved by the user. The user can then send the signature request by clicking "Continue" (or "Send" if the subject and message for the request have already been set).

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
createTemplate Emitted when the user creates the signature request template.
{
  templateId,
  templateInfo {
    title,
    message,
    signerRoles,
    ccRoles
  }
}
open Emitted when the HelloSign Embedded window has opened.
{
  url,
  iFrameUrl
}
cancel Emitted when the template 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 template flow without cancelling.
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
}