Quickstart - hellosign/hellosign-embedded GitHub Wiki

⚠️ Note: This article is intended for HelloSign Embedded v2. If you are using an older version of HelloSign Embedded, please refer to the documentation on our website.

• Introduction
• Prerequisites
• Creating the Signature Request
• Embedding the Signature Request

---

This quickstart guide will walk you through creating a signature request via HelloSign's API, obtaining its embedded signing URL, and then opening the embedded signature request in your own webapp using the HelloSign Embedded library.

If this all seems like too much work and you just want to see how HelloSign Embedded works, you can give HelloSign Embedded v2 a shot without having to make any API calls or write any code by checking out our Embedded Testing Tool. Just click the "Get Sample Document" button and we'll do all the work for you.

But if you want to continue here, make sure you have all the necessary prerequisites:

• A HelloSign.com account (they're free!).

• An API app. You can create one here.

• An API key. After you're verified your email, visit the API section of your account settings and click Reveal Key to find yours.

• A file to sign (.pdf, .doc, .pages, …).

Before you can sign a document using HelloSign Embedded, you first need a document to sign. Let's create a new signature request with your API Client using the HelloSign API (v3).

It's important to note that you may test the API as much as you'd like for free by just including the test_mode=1 parameter with your API calls, even if you haven't purchased an API plan — all you need is a free HelloSign account! This way you can test your integration without depleting the request quota if you have a paid API plan. However, signature requests sent in test mode won't be legally binding. You'll notice in the walk-through below that we use test_mode=1 for all API calls. Should you decide to send a real signature request, be sure to remove this parameter.

1. With your API Key and your API app's Client ID handy, let's make an API call to HelloSign's POST /signature_request/create_embedded endpoint to create the embedded signature request. For this step we'll be using a simple cURL call through the command line, but you can also use the HelloSign Node.js SDK or any one of HelloSign's other official SDKs. Note: It should go without saying that when building your app, never use the SDKs or make any API calls on the frontend, as this will dangerously expose your secret API key allowing bad actors the opportunity to impersonate you.

   Copy the code below and be sure to replace some fields with your own information.

   curl 'https://api.hellosign.com/v3/signature_request/create_embedded' \
     -u 'YOUR API KEY:' \
     -F 'client_id=YOUR CLIENT ID' \
     -F 'subject=My first signature request' \
     -F 'signers[0][email_address]=YOUR EMAIL' \
     -F 'signers[0][name]=YOUR NAME' \
     -F 'signers[0][order]=0' \
     -F 'file[0]=@YOUR FILE' \
     -F 'test_mode=1'

   When you're done, your API call should look something like this:

   curl 'https://api.hellosign.com/v3/signature_request/create_embedded' \
     -u 'abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789:' \
     -F 'client_id=abcdef0123456789abcdef0123456789' \
     -F 'subject=My first signature request' \
     -F 'signers[0][email_address][email protected]' \
     -F 'signers[0][name]=Alice' \
     -F 'signers[0][order]=0' \
     -F 'file[0][email protected]' \
     -F 'test_mode=1'

   Note: Your account will not be charged for sending requests created via the API with test_mode=1 (like the one above), however these requests are not legally binding.

2. Send the request. If all goes well, you should receive a response that looks something like this:

   {
     "signature_request": {
       "signature_request_id": "abcdef0123456789abcdef0123456789abcdef01",
       "test_mode": true,
       "title": "My first signature request",
       "requester_email_address": "[email protected]",
       // ...
       "signatures": [
         {
           "signature_id": "abcdef0123456789abcdef0123456789",
           "signer_email_address": "[email protected]",
           "signer_name": "Alice",
           // ...
         }
       ]
     }
   }

3. The last step is to obtain the embedded signing URL (signUrl) using HelloSign's GET /embedded/sign_url/[:signature_id] endpoint.

   In the response object of the previous API call, you should find a signature_id field within the first signatures object. You will need this ID for the next API call. Note: This is not the same as the signature_request_id which is the GUID for the entire signature request, not just a single signature.

   Copy the code below and, like before, be sure to replace some fields with your own information (and include the : at the end of your API key!).

   curl 'https://api.hellosign.com/v3/embedded/sign_url/SIGNATURE ID' \
     -u 'YOUR API KEY:'

   It should look something like this:

   curl 'https://api.hellosign.com/v3/embedded/sign_url/abcdef0123456789abcdef0123456789' \
     -u 'abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789:'

4. Send the request. If all goes well, you should receive a response that looks something like this:

   {
     "embedded": {
       "sign_url": "https://app.hellosign.com/editor/embeddedSign?signature_id=abcdef0123456789abcdef0123456789&token=abcdef0123456789abcdef0123456789",
       "expires_at": 1535074721
     }
   } 

5. Voila! We now have the embedded signing URL (signUrl). Hold on to this, because we will need it later.

Now that we have the embedded signing URL, we can pass it to HelloSign Embedded so that the signature request can be opened and signed from within our own application. The following steps assume that your frontend application is using a modern module bundler, like Webpack, Rollup, or Browserify. Alternatively, you can fetch the HelloSign Embedded library via CDN.

1. Install the HelloSign Embedded library via npm.

   npm install hellosign-embedded

2. Import HelloSign Embedded into your frontend app and instantiate a new HelloSign Embedded client with your API app's Client ID.

   Note: Avoid instantiating a new HelloSign Embedded client more than once, as this might lead to unexpected behavior and memory leaks. A common mistake is to instantiate a new client inside a click handler which is often called multiple times. Instead, instance HelloSign Embedded at the entry point to your application, or in a componentDidMount.

   import HelloSign from 'hellosign-embedded';
   
   const client = new HelloSign({
     clientId: 'Your client ID'
   });

   Or in Common JS style:

   const HelloSign = require('hellosign-embedded');
   
   // ...

   If you're confused or having trouble, you should know that we have a repo dedicated to getting started with HelloSign Embedded using a variety of different build/module systems. Take a look!

3. With your embedded signing URL (signUrl) handy, call client.open() to display the HelloSign Embedded iFrame to the user.

   client.open(signUrl, {
     testMode: true
   });
   
   client.on('sign', () => {
     alert('The document has been signed!');
   });

   We are using and testMode: true (alias of skipDomainVerification) here because it is useful when experimenting with the API. With the testMode option enabled, domain verification will be skipped which is useful for testing signature requests on domains that don't match the API app's registered domain (like localhost).

   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">

4. Congratulations! You just used HelloSign Embedded to embed and open a signature request from within your own webapp!