Getting Started with the HelloSign API in Python

"Getting Started with the HelloSign API in Python" header image

Thanks to eSignature tools like HelloSign, you don’t need to align schedules in order to put ink to paper. With a couple lines of Python, you can automate your eSignature workflow, allowing users to obtain legally binding eSignatures on their important documents with just a few clicks while saving them time, money and frustration. To get started, you can visit the HelloSign Developer Portal and start testing for free (no credit card required).


The HelloSign API gives you a powerful arsenal of tools for managing electronic signatures. We'll show you how, in just a few steps, you can begin using HelloSign with Python. This guide will walk you through getting connected to the API and explore one of its most integral features: sending signature requests.


Along the way, you'll build the foundational knowledge needed to begin building out your own HelloSign API workflows. Let's begin!

Get Set Up With HelloSign

Before we dive into making actual API calls, you'll want to get a few things set up.

First, you'll need to create an account. (Note: HelloSign, a Dropbox company, enables Dropbox users to use their existing account to log in)


With your account created, you can grab the credentials to access the API. From the HelloSign web app, click on your username in the top right corner. From the responding dropdown menu, click "My Settings." Then, navigate to the "API" tab. Here you can generate an API key.

Image of the HelloSign API Dashboard, highlighting the location to find your API key

You'll notice a banner that says, "Production access to the HelloSign API requires an API plan." That's why, for this guide, we'll take advantage of the free test mode HelloSign provides.

Prepare Your Python Environment

Now let's set up an environment for making calls with that HelloSign account. For readability, we'll be using the HelloSign Python SDK, but HelloSign supports many other languages. The concepts found within this guide apply to all of them.

First, check to make sure you're using Python 3. Open up a terminal and run the following command:

  
    python --version
    >> Python 3.9.1
  

If it's a version of Python 3, great! If not, you'll need to install Python from the official website. Do so, then run the previous command to ensure it's running on your system.

Now let's install the HelloSign Python SDK. There are a few ways to do so; one way is via pip. From the terminal, run the following command:

  
    pip install hellosign-python-sdk
  

If successful, you'll see output that ends in the following line:

  
    >>> Successfully installed hellosign-python-sdk-4.0.0
  

You have now installed everything you need to make calls to the HelloSign API. With that, we can get to work in a Python environment.

Open up a text editor (such as VS Code), and insert the following line to import the HelloSign Python SDK:

  
    from hellosign_sdk import HSClient
  

You’ll need your HelloSign API key in order to instantiate the client. Grab it from your settings page, and insert it within the following line:

  
    client = HSClient(api_key='<API-KEY>')
  

Remember to replace API-KEY with your HelloSign API key.


At this point, you should be able to access the API with your account. An easy way to check is to run the get_account_info (docs: GET /account)

  
    client.get_account_info()
  

If a HelloSign Account object is returned, then you're ready to begin sending signature requests with the API.


Protip: Look for the code snippets on each API method in the HelloSign API Reference documentation

Image showing the code snippets for the HelloSign Python API
Example Request with Python

Send Signature Requests

Sending signature requests with the HelloSign API is done with the Send Signature Request endpoint. Check out the documentation for a full list of optional parameters, but note that the following are required:

  • signers

  • files

To test it out, grab a PDF file from your computer and set yourself as a signer. The files parameter pulls in a local file. Another option is to use file_urls to specify a download URL for the file.


To test the API without a paid plan, you must set one other parameter: test_mode needs to be set to True. Be sure to note that when you do so, the signature is no longer legally binding.


So by putting all of that together, sending a signature request takes the form of this script:

  
    from hellosign_sdk import HSClient
    client = HSClient(api_key='<API-KEY>')
    client.send_signature_request(
            test_mode=True,
            title="title=Test Title.",
            subject="Test Subject",
            message="Please sign this.",
            signers=[{ 'email_address': 'alice.smith@email.com', 'name': 'Alice Smith' }],
            files=['test.pdf']
    )
  

Make sure you replace '<API-KEY>' with your API key and include the right name and email address for your test signers.


When you make the request, you’ll receive a signature_request_id. This will be useful later on when you want to check the status of the document.


Meanwhile, all signers of the file will receive an email that looks like this:

Image of signature request email

Go through and sign the document.

If you want to manually check on your signature requests at a later time, you can do so using the API. To check all the signature requests you have access to, use the List Signature Requests endpoint:

  
    signature_request_list = client.get_signature_request_list()
    for signature_request in signature_request_list:
            print(signature_request)
  

You'll get output listing all the relevant signature request IDs:

  
    SignatureRequest <SIGNATURE_REQUEST_ID>
    SignatureRequest <SIGNATURE_REQUEST_ID>
  

You can then use those IDs to see the status of the signature request. Do so with the Get Signature Request endpoint. You can also use the HelloSign API Dashboard to see API requests and responses. You even have the option of receiving the status of requests via callbacks.


Finally, you can use the API to download the signed copy:

  
    client.get_signature_request_file(
      signature_request_id='SIGNATURE_REQUEST_ID',
      filename='mySignedDocument.pdf'
    )
  

Remember to include the Signature Request ID of your signature request.

Build Your E-signature Workflow

There you have it! In just a few steps, you've sent out a signature request to an email address and then downloaded the signed copy.


So what's next? You can do so much more with the HelloSign API.


First, you might be interested in checking out the HelloSign API public Postman Collection. For further honing your signature requests, there’s a more in-depth Signature Request Walkthrough that introduces you to concepts such as templates and form fields. Of course, to see what else you can do with the API, be sure to check the 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.
true