Ashday's Digital Ecosystem & Development Tips Blog

eSignatures with Drupal: Integrating with the HelloSign API

Illustrations showing a person signing a document from their tablet

As more and more companies make the leap to having entirely-digital communications with their customers or clients, some things have a tendency to stay on paper.  One common thing which lags behind the rest of the digitization process is the signing of legally binding documents... but no more. Now, services such as HelloSign are able to fill this void, and thanks to the HelloSign API, Drupal websites can fully leverage that service to make this important task easier both for you and for your customers.

Why HelloSign?

One common question about eSignature services is simple: Why use one at all?

Using eSignatures can be a great time- and paper-saver compared to conventional document signing. With eSignatures, you can still print a hardcopy if you want, but it's not strictly necessary to do so... no more needing to keep a painstakingly organized file cabinet! It's also just what people have come to expect. If somebody is signing up for access to a web application, for instance, needing to print and send in a document feels archaic by comparison. For these reasons and more, the benefits of eSignatures seems clear.

But, why use a service for it? Can't you just add a checkbox to the registration page of your website that says "I agree"? Well, perhaps, but depending on your use-case that isn't always a suitable solution. Imagine, for instance, that the thing being signed is an apartment rental agreement. When somebody fills out a document like that, you want a signed PDF at the end... something for your own records, and something that the renter can refer to later to review the terms, so an eSigned document if much better than simply recording that somebody clicked a button.

Furthermore, you also need the signature to be legally binding. Unless you want to navigate all of the laws to figure out how to make an eSignature be just as binding as a physical signature, using a service that has already figured out all of those details is a fantastic solution.

At Ashday, we like HelloSign because, in addition to meeting all of these needs and having many other useful features, we can use the robust HelloSign API to integrate the eSignature process directly into websites that need it.

Interested in a smooth, hassle-free HelloSign Integration?  Request your free consultation with an Ashday Drupal expert today. 

Drupal 7 Integration: Overview

Our first HelloSign integration was with a Drupal 7 site, and with that, we created and released the initial version of our HelloSign module for Drupal. This module can be used by any Drupal 7 website to facilitate the integration of HelloSign with that site.

Since this is an integration, somebody using the module still needs to have a HelloSign account that includes access to the HelloSign API and, for the best user experience, its embedded signing feature. What this module does is help get your Drupal 7 site connected to your HelloSign account and provide some useful tools for creating and managing eSignature requests.

The way the module works is simple. Once it is enabled on your site, there will be a page available on your site to enter your HelloSign API credentials. This page also has a useful "Test Mode" option to toggle whether eSignatures on the site should be "real" or just tests, which is very useful for when you are making changes to your eSignature functionality and want to be sure that it all works before people start signing any legally binding documents.

Once the HelloSIgn connection has been established, you're ready to actually use the module. Some Drupal modules create a full-fledged user interface for interacting with them, but since eSignatures can be used for so many different things, we didn't want to make any wrong assumptions about what people would want to do with the module. As such, what this module provides is a set of useful PHP functions that greatly simplify the creation of a HelloSign integration, rather than building a whole UI that might not work for all sites.

Drupal 7 Integration: The Details

If you hire a company like Ashday to build your website, of if you have software engineers at your company, they'll be the ones using the module to create an integration with the HelloSign API. In this case, you can probably skip this section. If, on the other hand, you're writing the code yourself, then this section is for you! The module's README has more details, but this should give a good overview of the overall process for using the module to integrate with the HelloSign API.

The heart of the module is the PHP function hellosign_generate_esignature_request(). All this function needs is the location of the PDF file to be signed, the names and email addresses of everyone who should sign it, a title for the document being signed, and a subject line for any emails sent regarding the eSignature. You can also create the eSignature in either "email" or "embedded" mode; we'll use "embedded" mode, since that usually makes for a better user experience. With this information, the function connects to the HelloSign API and starts the eSignature process. Assuming that all goes well, the function returns the ID of the signature request as well as information about the individual signatures needed. The request ID can then later be used by other functions to do other things related to the eSignature, such as cancelling the request, and the signature information can be used to move on to the next step: Building a page where the user can actually sign the document.

Perhaps surprisingly, this is one of the easiest parts of the integration.  The module includes a function called hellosign_get_embed_url(); give it the ID of a particular signature that you want, and it will return the URL for an iframe which you can include on whatever page you want users to go to to sign their documents.

Now, this is a Drupal 7 module, and what would a Drupal 7 module be without hooks? This module provides a single, vital hook: hook_process_hellosign_callback().  Any implementations of this hook that you create will get called whenever HelloSign notifies the site about a signature request being updated. This way, your site can know when a document gets signed or completed, and can do anything that it needs to. Need to save a copy of the signed document to your own server? The module has that covered as well. Just use hellosign_fetch_esignature_document() to get exactly the file you need, and then save it wherever you want in the file system.

Finally, if you need other, more advanced features of the HelloSign API, the module ultimately uses the HelloSign PHP SDK, so you can leverage anything you need from that even if the Drupal module doesn't specifically include functions for it. In theory, you could even create a HelloSign integration using just the SDK, but the Drupal module handles many common eSignature needs without ever needing to delve into a much more complicated utility like the SDK.

What's Next: Drupal 8

Of course, at this point, Drupal 7 is old news, and Drupal 8 is what all the cool kids are talking about. Well, don't worry: We're currently working on a new version of our HelloSign module for use on Drupal 8 sites. We've been using Drupal 8 for more than two years now (since before it's first official release!) and at this point we're pretty comfortable with the Drupal 8 way of doing things, so it's high time we brought the HelloSign module up to date. Since Drupal 8 is a much more robust and object-oriented system than Drupal 7, we're fully leveraging that to improve the structure of the module. This makes it both more flexibile to use and easier to add new features to as new needs crop up. Expect another blog post once the module is ready for use, and you can see all the improvements for yourself.

We're looking forward to building HelloSign integrations in Drupal 8 sites ... stay tuned.  

Free offer, talk to a seasoned Drupal expert.

Updated: Dec 6, 2017 1:00:00 PM