3 Questions to Answer When Integrating the HelloSign API

Share Button

I’m a senior member of HelloSign’s API support team, so I see a lot of different API use cases. Each new customer brings a unique set of variables to the table. But despite the differences per customer case, there a few core questions that unfailingly come up. These questions need to be answered before we can get the ball rolling.

We thought it would be helpful to add a top-level overview of some of the core components of our API with some of the basic questions that need to be asked as you plan your integration.

This post will be geared slightly towards a more technical audience. We also have a helpful post about the “6 Steps For Getting Started With the HelloSign API” for non-technical folks.

The top three questions to ask as you’re planning your integration are:

  1. Who is creating my document?
  2. Where do I want the signers to go when signing?
  3. How should I structure my requests for fiscal efficiency?

1. Who is Creating my Document?

There are typically three ways people generate documents that they need signed:

  • Programmatically
  • Provided by users
  • Static documents

Each method opens different sets of options for processing the documents. Below we’ll go over what options become available to you in each case.


If you’re creating your document programmatically, you’ll use different endpoints and have different options than you will if you’re using HelloSign’s concept of templates.

When creating the document on the fly, typically the first question we get asked by our customers is “How do we tell HelloSign where the signers should sign?”

You have a few options, though the most common approach is to use Text Tags. These are specifically formatted blobs of text on the document itself that HelloSign will convert into signer elements.

An example of this would be [sig|req|signer0]. That text would be converted into a signature box. It’s required to be signed, and it’s assigned to signer0.

You have quite a few options with Text Tags, so check out the walkthrough linked above for details.

HelloSign also supports programmatic placing of signer elements using a coordinate system, which we call form_fields_per_document.

Basically, that system allows you to place signer elements by passing us the x, y, height, and length of each element as an argument in the POST body.

Here’s an article specifically about how that system works.

If you don’t use Text Tags or form_fields_per_document, HelloSign will automatically append a HelloSign Signatures Page, where all signers included in the signature request will sign. That document then becomes part of the final document and captures the signers’ signatures.

Provided by the users

If the document is coming from the users of your platform, and you’d like for those users to have an interface where they’re placing signature elements, you have a few options.

You can allow them to upload their documents to be used as one-off documents, where they can create their signature request and set the signers/declare cc email addresses, by using what we call Embedded Requesting.

That will allow you to power a HelloSign iframe on your site, capture the signer information from the requester (or include the signer information from your platform), let the requester place all of the signer elements (like signature boxes, date fields, text boxes, etc) similar to how the “Request A Signature” process works on hellosign.com.

You can also allow the requesters to upload a document, place those signer elements, and create a template from that so they can reuse the formatted document as many times as they’d like.

That process is called Embedded Templates, and you can read more about it in the link. One of the most powerful details to take advantage of here is the ability to allow your users to merge data when the template that they’re creating is used in a signature request. This is done through Merge Fields.

Note that Embedded Templates can be combined with Embedded Requesting to make for a really comprehensive and powerful signature request creation process, if you want that kind of flexibility.

Static documents

If you’re using the same set of documents over and over, you could use the HelloSign concept of templates. This is different from the Embedded Template approach above, as you’d actually be creating these templates on hellosign.com using the account that owns the API Key that you’re using to authenticate your calls, then using those templates in signature requests sent from your platform.

Using either embedded or hellosign.com templates comes with some powerful advantages. The most asked about is the ability to pass information from your platform through the API to HelloSign, which HelloSign will merge onto the template.

This is accomplished using our Custom Fields parameter (sometimes referred to as “merge fields”, though this shouldn’t be confused with HelloSign’s Embedded Templates Merge Fields). When you’re placing signer elements on the template and assigning the roles for Who fills this out, any textbox and checkbox assigned to “Me (when sending)” becomes a custom field.

2. Where do I want the signers to go when signing?

Once you understand how the documents will be created, you’ll want to determine who will host the signing transaction.

There are two options:

  • Let HelloSign.com host the signer page and send emails to signers
  • Host the signer page on your platform and handle signer notifications

Both are powerful, though companies tend to lean towards one or the other depending on how much control they want over the signing process. Let’s take a look at the differences.

Let HelloSign.com host the signer page

We call this approach a standard Signature Request. This approach can be used with all/any of the answers to the main question above (Who is creating my document?).

With non-embedded signing, HelloSign sends an email notification to the signers with a link to the signing page. That link leads to a hellosign.com signer page.

Once all of the signers are done, they’ll receive an email from HelloSign either with a copy of the signed completed document attached or with a link to HelloSign.com where they can view/download the completed document.

Host the signer page on your platform

If you’d like to control the signer experience, you could instead use what we call Embedded Signing. Embedded Signing allows you to control the signer experience. You host a signature page on a domain that you own, where you open up an iframe with very little required code.

This is extraordinarily powerful, as it gives you ultimate control over how the signer interacts with your platform. If you have a flow where you want the signer to stay on your site all the way through a process, you can do that with Embedded Signing.

Keep in mind that with Embedded Signing, HelloSign will not send any emails to the signers or to your platform. You have complete control over the communication, which means that your platform is responsible for verifying that the signers are who they say they are.

Here’s a great FAQ on some of the big key points between Embedded vs Non-Embedded.

3. How Should I Structure My Requests for Fiscal Efficiency?

If you take a look at our HelloSign API Pricing page, you’ll see that we allot a certain number signature requests for each plan. This means the way you structure your implementation can have an impact on the cost for the API.

Since the Signature Requests are the billable actions, you’ll want to structure the integration in a way that uses the fewest amount of signature requests possible.

This could mean that you don’t trigger the signature request action until you’ve collected a good amount of information from the signers/requesters. Or you wait to trigger the signature request until the signer takes some specific action on your platform that tells you they’re ready to sign.

Another biggie that can be easy to miss is when you should trigger embedded signature requests. The flow here is rather straightforward: trigger an embedded signature request, then use the signature_id for each signer (returned in the signature request object response to your POST that created the signature request) to GET a sign_url that you use to power the iframe on the client side.

What if the signer decides to close the iframe, or navigates away from the page, then comes back later to sign the same signature request? In that case, you should have your integration request a new sign_url (which uses the same signature_id in the same signature request object) when the signer returns to this signature request, instead of generating a new signature request from scratch. This means you’re only charged for the one signature request, even though your signers can have multiple sessions and access the one request multiple times.

We’re always happy to help!

I hope this article has been helpful and has given you some insights into the incredible power and flexibility of the HelloSign API.

If you have any questions, or if you’d like to talk to us about your implementation before you get started, write to us at apisupport@hellosign.com. You can also get started with the API right now by going here.