Embedded Requesting Walkthrough

Embedded Requesting allows you to have users create and send signature requests on your site in an iFrame using hellosign-embedded, HelloSign's official client-side library. The documentation below describes requirements and setup steps for the embedded requesting flow.

Preliminary

Please complete the steps below before following along with the content.

  1. 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. However, you can use skipDomainVerification to embed requests created using test_mode.

  1. Save your API app's Client ID and API Key, which you'll need to use this feature.

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 in the Server Side section below.

Server Side

The very first step is to create a "draft" signature request from the 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):

curlphpjavapythonrubynodejsdotnet
Copy
Copied
curl 'https://api.hellosign.com/v3/unclaimed_draft/create_embedded' \
    -u 'SIGN_IN_AND_CREATE_API_KEY_FIRST:' \
    -F 'client_id=YOUR_CLIENT_ID' \
    -F 'file[0]=@NDA.pdf' \
    -F 'requester_email_address=jolene@example.com' \
    -F 'test_mode=1'
{
    "unclaimed_draft": {
        "claim_url": "https://embedded.hellosign.com/prep-and-send/embedded-request?cached_params_token=30c4d8df776038c2fa5f7094c3718937",
        "expires_at": 1414093891,
        "signature_request_id": "11756571ad74f8ecb1a0ddc80375a9e44bad8ba6",
        "requesting_redirect_url": null,
        "signing_redirect_url": null,
        "test_mode": true
    }
}
Copy
Copied
$client = new HelloSign\Client('SIGN_IN_AND_CREATE_API_KEY_FIRST');
$request = new HelloSign\SignatureRequest;
$request->enableTestMode();
$request->setRequesterEmail('jolene@example.com');
$request->addFile($path_to_nda_pdf);
$client_id = 'YOUR_CLIENT_ID';
$draft_request = new HelloSign\UnclaimedDraft($request, $client_id);
$response = $client->createUnclaimedDraft($draft_request);
Copy
Copied
SignatureRequest sigReq = new SignatureRequest();
sigReq.setTestMode(true);
sigReq.addFile(new File("NDA.pdf"));

UnclaimedDraft draft = new UnclaimedDraft(sigReq, UnclaimedDraftType.request_signature);
draft.setIsForEmbeddedSigning(false);
draft.setRequesterEmail("jolene@example.com");

String clientId = "YOUR_CLIENT_ID";
EmbeddedRequest embedReq = new EmbeddedRequest(clientId, draft);

HelloSignClient client = new HelloSignClient("SIGN_IN_AND_CREATE_API_KEY_FIRST");
UnclaimedDraft responseDraft = (UnclaimedDraft) client.createEmbeddedRequest(embedReq);
Copy
Copied
client = HSClient(api_key='SIGN_IN_AND_CREATE_API_KEY_FIRST')
client.create_embedded_unclaimed_draft(
    test_mode=True,
    client_id='YOUR_CLIENT_ID',
    draft_type='request_signature',
    requester_email_address='jolene@example.com',
    files=['NDA.pdf']
)
Copy
Copied
client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
client.create_embedded_unclaimed_draft(
    :test_mode => 1,
    :client_id => 'YOUR_CLIENT_ID',
    :type => 'request_signature',
    :subject => 'The NDA we talked about',
    :requester_email_address => 'jolene@example.com',
    :files => ['NDA.pdf']
)
Copy
Copied
const hellosign = require('hellosign-sdk')({ key: 'SIGN_IN_AND_CREATE_API_KEY_FIRST' });

const opts = {
  test_mode: 1,
  clientId: 'b6b8e7deaf8f0b95c029dca049356d4a2cf9710a',
  type: 'request_signature',
  subject: 'The NDA we talked about',
  requester_email_address: 'alice@example.com',
  files: ['NDA.pdf']
};

hellosign.unclaimedDraft.createEmbedded(opts).then((res) => {
  // handle response
}).catch((err) => {
  // handle error
});
Copy
Copied
var client = new Client("SIGN_IN_AND_CREATE_API_KEY_FIRST");
var draft = new SignatureRequest();
draft.AddFile("NDA.pdf");
draft.RequesterEmailAddress = "jolene@example.com";
draft.TestMode = true;
var response = client.CreateUnclaimedDraft(draft, "YOUR_CLIENT_ID");

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.

curlphpjavapythonrubynodejsdotnet
Copy
Copied
curl 'https://api.hellosign.com/v3/unclaimed_draft/create_embedded' \
    -u 'SIGN_IN_AND_CREATE_API_KEY_FIRST:' \
    -F 'client_id=YOUR_CLIENT_ID' \
    -F 'file[0]=@NDA.pdf' \
    -F 'requester_email_address=jolene@example.com' \
    -F 'is_for_embedded_signing=1' \
    -F 'test_mode=1'
Copy
Copied
$client = new HelloSign\Client('SIGN_IN_AND_CREATE_API_KEY_FIRST');
$request = new HelloSign\SignatureRequest;
$request->enableTestMode();
$request->setRequesterEmail('jolene@example.com');
$request->addFile($path_to_nda_pdf);
$client_id = 'YOUR_CLIENT_ID';
$draft_request = new HelloSign\UnclaimedDraft($request, $client_id);
$draft_request->setIsForEmbeddedSigning(true);
$response = $client->createUnclaimedDraft($draft_request);

$claim_url = $draft_request->getClaimUrl();
Copy
Copied
SignatureRequest sigReq = new SignatureRequest();
sigReq.setTestMode(true);
sigReq.addFile(new File("NDA.pdf"));

UnclaimedDraft draft = new UnclaimedDraft(sigReq, UnclaimedDraftType.request_signature);
draft.setIsForEmbeddedSigning(true);
draft.setRequesterEmail("jolene@example.com");

String clientId = "YOUR_CLIENT_ID";
EmbeddedRequest embedReq = new EmbeddedRequest(clientId, draft);

HelloSignClient client = new HelloSignClient("SIGN_IN_AND_CREATE_API_KEY_FIRST");
UnclaimedDraft responseDraft = (UnclaimedDraft) client.createEmbeddedRequest(embedReq);
Copy
Copied
client = HSClient(api_key='SIGN_IN_AND_CREATE_API_KEY_FIRST')
client.create_embedded_unclaimed_draft(
    test_mode=True,
    client_id='YOUR_CLIENT_ID',
    draft_type='request_signature',
    requester_email_address='jolene@example.com',
    is_for_embedded_signing=True,
    files=['NDA.pdf']
)
Copy
Copied
client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
client.create_embedded_unclaimed_draft(
    :test_mode => 1,
    :client_id => 'YOUR_CLIENT_ID',
    :type => 'request_signature',
    :subject => 'The NDA we talked about',
    :requester_email_address => 'jolene@example.com',
    :files => ['NDA.pdf'],
    :is_for_embedded_signing => 1
)
Copy
Copied
const hellosign = require('hellosign-sdk')({ key: 'SIGN_IN_AND_CREATE_API_KEY_FIRST' });

const opts = {
 test_mode: 1,
 clientId: 'b6b8e7deaf8f0b95c029dca049356d4a2cf9710a',
 type: 'request_signature',
 subject: 'The NDA we talked about',
 requester_email_address: 'alice@example.com',
 files: ['NDA.pdf'],
 is_for_embedded_signing: 1
};

hellosign.unclaimedDraft.createEmbedded(opts).then((res) => {
  // handle response
}).catch((err) => {
  // handle error
});
Copy
Copied
var client = new Client("SIGN_IN_AND_CREATE_API_KEY_FIRST");
var draft = new SignatureRequest();
draft.AddFile("NDA.pdf");
draft.RequesterEmailAddress = "jolene@example.com";
draft.IsForEmbeddedSigning = true;
draft.TestMode = true;
var response = client.CreateUnclaimedDraft(draft, "YOUR_CLIENT_ID");

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.

In this section, you created an Embedded Signature Request for jolene@example.com. When Jolene accesses the embedded request, she'll make edits to the signature request and send it out once complete. You'll need to grab the claim_url from the JSON response. The claim_url is passed to the Client Side to use in HelloSign Embedded's open() method.

Client Side

We provide a client-side library that handles the authorization and display of the embedded request using an iFrame. You can use this feature by adding a few lines of JavaScript code.

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

Copy
Copied
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 claimUrl and API client ID. Note that we're using skipDomainVerification when calling this method. You can learn more about that in the Domain Restriction section below.

Copy
Copied
import HelloSign from 'hellosign-embedded';

const client = new HelloSign();

client.open(claimUrl, {
  clientId: 'Your API client ID',
  skipDomainVerification: true,
});
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():

NameTypeDescription
requestingEmailstringThe email of the account issuing the signature request.

Note: This option is only necessary for 'Me and Others' type signature requests.

Example:
{
requestingEmail: alice@example.com
}
localestringThe 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
}
redirectTostringWhere the user will be redirected after sending the signature request.

Example:
{
redirectTo: 'http://example.com'
}
allowCancelbooleanWhether the user should be able to close the iFrame without finishing the request. Default: true.

Example:
{
allowCancel: false
}
debugbooleanAllows 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
}
skipDomainVerificationbooleanWhether 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
}
timeoutnumberHow long (in milliseconds) to wait for the HelloSign app to initialize before aborting. Default: 30000 (30 seconds).

Example:
{
timeout: 10000
}
containerHTMLElementBy 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')
}

Additional Notes

App Approval

In order to ensure that integrations adhere to eSignature regulations and best practices, an app approval is needed prior to moving into production for all customers implementing embedded signing, embedded requesting, embedded templates, and OAuth workflows.

Note

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

Please refer to the App Approval Section for more detailed information about getting your app approved.

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:

Copy
Copied
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 in the section above.

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 send event will be appended to the url query string.

Text Tags

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

Client Side 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.

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

Here are a list of possible events:

EventDescriptionData
sendEmitted when the user sends the signature request.
{
signatureRequestId,
signatureRequestInfo {
title,
message,
signatures,
ccEmailAddresses
}
}
openEmitted when the HelloSign Embedded window has opened.
{
url,
iFrameUrl
}
cancelEmitted when the signature request was canceled by the user by either pressing the close button or selecting "close" from the dropdown list.
finishEmitted when the user has finished the embedded signature request flow without cancelling. However, the user may have declined or reassigned the signature request.
messageEmitted when HelloSign Embedded has received a cross-origin window message from the HelloSign app.
{
type,
payload
}
closeEmitted when the HelloSign Embedded window has closed.
errorEmitted when the HelloSign app encounters an error.
{
signatureId,
code
}