Creating Approval Workflows with Multiple Signers

"Creating Approval Workflows with Multiple Signers" header image

Approval workflows with multiple signers are everywhere! You might find a parent signing their newly licensed dependents onto their existing car insurance policy, or a group of college grads co-signing a rental lease on a new house. In business, lengthier processes like mergers and acquisitions will inevitably lead back to lengthy and complex legal documents with multiple levels of approval.


In any scenario, dealing with multiple signers in a signature-based approval workflow is hard. With physical documents you might get lucky and have everyone in the same place. However, this can get overly complicated if that’s not the case or if new signers are added at different stages, and might require multiple phone calls or meetings to obtain signatures from all parties.


In this article we’ll examine how you can use the HelloSign API to build great signing experiences for your users, especially in approval flows with multiple signers.

Send Documents to Multiple Signers

Preliminary

Please complete our official Quick Start if you’d like to use the samples in this article. We’re going to be using the HelloSign NodeJS SDK throughout.

Send signature request

Imagine you’re running a business where many of the employees are remote, and you just started offering them corporate cards to take care of simple transactions. Quickly you realize that you need a process in place that can handle multiple approvers, especially for bigger purchases, and the ability to notify Finance for record keeping. Because teams might be geographically spread out, it’s not only fine for signing to happen at different times, it’s actually necessary.

You can accomplish this using the HelloSign API by calling Send Signature Request (/signature_request/send) and passing multiple signers. You can even specify the order and send a carbon copy to the finance department so they receive the approved expense report.

  
    const hellosign = require('hellosign-sdk')({ key: 'YOUR_API_KEY' });
    
    const options = {
      test_mode: 1,
      title: 'Employee purchase escalation',
      subject: '[Review] Expense report exceeds limit',
      message: 'Please review and approve this expense report as it exceeds the limit for company policy',
      signers: [
        {
          email_address: 'taylor@example.com',
          name: 'Taylor',
          order: 0
        },
        {
          email_address: 'roshawn@example.com',
          name: 'Roshawn',
          order: 1
        }
      ],
      cc_email_addresses: ['finance-dept@example.com'],
      files: ['sept-expenses-2021.pdf'],
      metadata: {
        clientId: '1234',
        custom_text: 'Expense Report Exceptions'
      }
    };
    
    hellosign.signatureRequest.send(options).then((res) => {
      console.log(res)
    }).catch((err) => {
      console.log(err)
    });
  

In the request above, we’re sending a signature request to Taylor who manages Roshawn. After Taylor receives and signs the request, Roshawn is able to sign the report before sending a completed copy to the finance department. We specified the signing `order` with the order parameter. We’re also making use of `metadata` to store a unique string on the signature request. In production, you might do this so you can easily identify the signature request in the future through search.

Embed Documents for Multiple Signers

Now let’s look at a different scenario where we typically see signing complexity increase with multiple parties involved. Pretend you’re building a web app to help banks and FinTech companies complete approval workflows more quickly. Because your target clientele is sensitive about security and customer data, you want to avoid sending them outside of the app to conduct different aspects of the approval workflow.

You can use the HelloSign API to build embedded signing directly into your app. This signing flow has a few additional steps: generating the embedded signature request, creating an embedded object, and embedding the signature request into the front end of your app. This signing flow requires special consideration when building for multiple signers, which we’ll cover in the context of the example below.

Generating an embedded signature request

The first step is calling Send Embedded Signature Request (/signature_request/create_embedded):

  
    const options = {
      test_mode: 1,
      clientId: 'b6b8e7deaf8f0b95c029dca049356d4a2cf9710a',
      title: 'Transfer request over 50k',
      subject: 'Request completed',
      message: 'Please review this completed transfer request',
      signers: [
        {
          email_address: 'yuri@example.com',
          name: 'Yuri',
        },
        {
          email_address: 'charlie@example.com',
          name: 'Charlie',
        }
      ],
      files: ['large-xfer-request.pdf']
    };
    
    hellosign.signatureRequest.createEmbedded(options).then((res) => {
      const signatureArr = res.signature_request.signatures;
      // save signature array to database
    }).catch((err) => {
      console.log(err)
    });
  

The request above will return a signature request object. Within that object, there’s an array of `signatures`. Every entry in that array represents a unique `signature` object for each individual signer (even if they’re signing the form in multiple places). In an embedded signing flow with multiple signers, we recommend saving that `signatures` array to a database, where you can retrieve the respective `signature` as needed when a party is ready to sign.

Creating an embedded object

Once a signer logs into your app and is ready to complete their signature, you’ll need to generate an embedded object for them. The subsequent `sign_url` can be embedded into the front end of your app. You’ll need a unique `sign_url` for each respective signer on your signature request.

Each signature object contains a unique `signature_id`, which gets passed to Get Embedded Sign URL (/embedded/sign_url/:signature_id) when that party is ready to sign.

  
    // read signatureArr from database
    // you'd need your own logic for finding the right signature
    const yuri_signature_id = signatureArr[0].signature_id;
    
    hellosign.embedded.getSignURL(yuri_signature_id).then((res) => {
      console.log('The sign url: ' + res.embedded.sign_url);
      res.send(res.embedded.sign_url);
    }).catch((err) => {
      console.log(err)
    })
  

The temporary `sign_url` from the embedded object must be passed passed to the front end of your application, where it can be embedded in an iFrame.

Embed signature request on front end

The embedded signing functionality relies on a client side library called hellosign-embedded. You’ll need to include this library in the front end of your app through a package manager (such as npm) or cdn.

Using the `sign_url` you passed from your back end, you can call the `open()` method available on the hellosign-embedded library.

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

Note that this JavaScript implementation is suitable for inserting into a `<script>` tag in plain HTML. In production you’d likely use a front end framework such as React or Django. The important part is that this code executes in the context of your browser.

Using embedded signing with multiple signers

Creating a great embedded signing experience in an approval flow with multiple signers depends on effectively managing the flow of information in your app. In general, you’ll want to create and store the signature request. As signers access your app, you’ll pull up the signature request (likely by `signature_request_id`), grab their corresponding `signature_id`, create a `sign_url` that gets passed to your front end, and embed it into an iFrame using hellosign-embedded. You’ll repeat that process for each respective signer. Once the document is completed it will be sent to all parties.

Delighting multiple signers

When your business is moving from pen and paper to eSignature, the complexity of approval workflows that require multiple signers can be scary. But don’t let that stop you! Digitizing legacy approval workflows that rely on signature is a huge value add for your business. The HelloSign API offers two main signature flows, embedded and non-embedded, that can help you implement seamless approval workflows for multiple signers. You can learn about our other API features and find additional resources in our developer portal. Happy signing!

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.