Getting Started with the HelloSign API Using Node.js

"Getting Started with the HelloSign API Using Node.js" header image

If you’re a Node.js developer and need to integrate eSignatures into your app or website, then you may need a solution that is not only reliable, but also easy to implement. The HelloSign API is a fully customizable eSignature API that is secure, scalable, and ranked #1 for Ease of Implementation compared to other eSignature vendors on G2. To get started, you can visit our Developer Portal and start testing for free (no credit card required).

In this blog post, we’ll dig into the HelloSign API from the perspective of a Node.js developer.

Building with the HelloSign Node.js SDK

Using the test_mode parameter, we’re going to walk through some examples on how to integrate eSignatures with the HelloSign Node.js SDK, which contains lots of great information in the README file. You can also find the Node.js implementation for each API method in the HelloSign API Reference documentation:

Image of an example Request/Response using the HelloSign API with Node.js
Example Request/Response with Node.js

Scenario:

Pretend you’re building an app that allows homeowners to auction short term rentals to guests during peak demand periods for that location, such as a college graduation, concert, or pro sports event. When an auction ends successfully, the homeowner and guest must both sign a rental agreement. Depending on the user experience you want to provide, there are multiple ways the HelloSign API could facilitate signing.

Sending a Signature Request for the Rental Agreement

In this scenario, both parties would receive a signature request for the rental agreement over email and complete the signature on the HelloSign website. Read through the Signature Request Walkthrough for more information.

Here are two different approaches to accomplish this:

Signature Request using Files

Send a signature request for the rental agreement by calling Send Signature Request with signatureRequest.send():

  
    const options = {
      test_mode: 1,
      title: 'Rental Agreement for owner and guest',
      subject: 'Your Rental Agreement',
      message: 'Please sign this rental agreement to confirm the reservation',
      signers: [
        {
          email_address: 'owner@example.com',
          name: 'Owner Name'
        },
        {
          email_address: 'guest@example.com',
          name: 'Guest Name'
        }
      ],
      files: ['fake_rental_agreement.pdf']
    };
    
    hellosign.signatureRequest.send(options).then((res) => {
      // handle response
    }).catch((err) => {
      // handle error
    });
  

Note that the files parameter is using a path to a single file, but can also be used with a URL or include multiple files in the signature request. For URLs, you will use file_url : [array] instead.

Signature Request using Templates

Use a Template to allow parties to sign the contract with their fields already pre-formatted.

Since the rental agreement must be signed for each rental, using a template can create a faster signing experience for owners and guests with the required fields already inserted in the right places. Read through the Templates Walkthrough for more information.

First, a template is created in the HelloSign user interface:

Image of template preparation via the HelloSign User Interface
Template preparation via the HelloSign User Interface

Now, you can reference the template with template_id and call Send with Template using signatureRequest.sendWithTemplate():

  
    const options = {
      test_mode: 1,
      template_id: '5eb54aaaa71ce8dcaec5d26e93a2754af1712606',
      title: 'Rental Agreement for owner and guest',
      subject: 'Your Rental Agreement',
      message: 'Please sign this rental agreement to confirm the reservation',
      signers: [
        {
          email_address: 'owner@example.com',
          name: 'Owner Name'
          role: 'Owner'
        },
        {
          email_address: 'guest@example.com',
          name: 'Guest Name'      
          role: 'Guest'
        }
      ]
    };
    
    hellosign.signatureRequest.sendWithTemplate(options).then((res) => {
      // handle response
    }).catch((err) => {
      // handle error
    });
  

Embed eSignature Functionality in your Rental App

Pretend you want to keep users in your rental app and complete their signatures on that surface. The HelloSign API allows you to create a seamless signing experience for your users by embedding the signature workflow directly into your app. Instead of building the workflow from scratch, you can now focus your efforts on customizing the workflow exactly the way you want it. With the HelloSign API, you can let users do an assortment of tasks directly in your app, like sign documents with Embedded Signing, request signatures with Embedded Requesting, and create and edit templates with Embedded Templates. You can even White Label the entire signing flow with your own branding to make the experience completely seamless.


Developers building embedded flows will need to interact with the front end and back end of an app. Back end calls are made via the HelloSign Node.js SDK and the corresponding links are embedded in an iFrame on the front end using the hellosign-embedded library. We’ll cover embedded flows in Node.js more in depth in a future blog post.

Example uses:

  1. You want users to sign the rental agreement from their user dashboards. You can use Embedded Signing to allow owners or guests to sign the rental agreement directly from your app.
  2. Some owners have additional paperwork or would rather provide their own. They need to upload their documents, place fields, and send a signature request. If you build with Embedded Requesting, then owners can create and send signature requests from your app.

Using the Node.js SDK to build with the HelloSign API

For developers building with HelloSign, the HelloSign Node.js SDK is a great way to improve efficiency and speed up implementation. Whether you’re building for signature requests or embedded signing, the Node.js SDK offers quick access to HelloSign API endpoints using built-in methods. The samples below can be a helpful way to get started.

Embedded Samples:

Blog post: Embedded Requesting Workflows Using the HelloSign and Dropbox APIs

Blog post: Embed a CLA Signing Page Using NodeJS with the HelloSign and Github APIs

To learn more about the HelloSign API and start testing for free, visit HelloSign’s Developer Portal

Ready to integrate signatures into your app or website?

Let us help you build a custom API plan that fits your unique business needs.

Get news, insights and posts directly in your inbox

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form
Oops! Something went wrong while submitting the form.