When your application requires users to sign contracts and agreements, you likely want to keep the experience on your site. You can maintain control of what users see and still have the benefits of a secure eSignature platform.

Just as Django allows you to build more with less code, HelloSign’s embedded eSignatures give you the tools to create a great experience, this allows your users to address their business needs in a unique and customized approach — whether it’s to improve an HR onboarding experience for new employees or to streamline contracting for a sales team. In this guide, we will be using a sample project which allows teachers in a school to have different forms signed by parents, we’ll walk you through how to create a custom premium branded eSignature flow for Django, from installing the HelloSign SDK in pip to finishing with a script import into your Django templates.

To get started, you can visit our Developer Portal and start testing for free (no credit card required).

Add HelloSign to your app’s Virtual Environment and Customize with Premium Branding

You will want to create your Django project with two apps: an admin app and a user portal app.  

Inside your project’s virtual environment, install HelloSign’s Python SDK.  Be sure that it is available to both the admin and user apps.

You will need to create a HelloSign account to generate an API key.  You can find your API key under the API tab on the Settings page of your account.  You will also need to create a HelloSign API App. In the same page where you get the key, click on “Create” in the API Apps section.  Give your API App a name and a domain. While you are in the testing phases of development, you can ignore the domain verification fields on the HelloSign dashboard or enter any URL you like, as those are only required for production uses.

Once you have created an application, you will receive a Client ID associated with that specific API App.  As a best practice, secure both your API key and Client ID in a .env file.  

By using the Premium Branding feature, you can customize the look of your HelloSign eSignature experience to match your organization’s color scheme.  Using the Update API App endpoint and initiating the API call from the admin side of your Django project, specify the elements you would like to customize:

littleschool/admin/views.py

‍

You can find more information in the Premium Branding documentation

Create a Forms Page for Users

HelloSign offers developers the ability to embed the signing experience directly in their websites, making the process of collecting documents with legally-binding eSignature from your clients or users feel like a seamless part of their experience on your website.

The Little School, has a website built in Django to accommodate Parent, Child, and Teacher profiles, making use of Django’s built-in auth features.  Each Parent object is associated with a specific authenticated User:

littleschool/models.py

‍

When parents log in to the school’s website, they are directed to a list of forms in the parent_portal app within the Django project file. Here, the school can post enrollment forms, field trip permission slips, and health forms.  All the files available through these links can be handled with the HelloSign client, creating a centralized location for all the school’s required waivers and contracts.

If a project is set up with a relational database, including the default sqlite3, an admin user could control which forms appear on a given user profile by using the Teacher-Child relationship in models.py to send certain forms to a Parent user’s views.

Create HelloSign Client and Methods

The embedding signing flow means users can view, sign, and review their contracts and waivers while still on your website.  Using HelloSign’s Embedded Signing functionality allows you to display your SignatureRequests as <iframe> HTML elements and does not require any additional user accounts or authentication beyond what you already have on your site.  

Inside the parent_portal file directory, create a file called hellosignclient.py.  In this file, you will add the code to create embedded eSignature requests and display documents for signature at a unique URL.  You can create a single SignatureRequest method and reuse it for multiple forms:

littleschool/parent_portal/hellosignclient.py

‍

Here, we are using the pip package python-decouple to handle variables from our .env file.  

Then, we import the HelloSign Client and Django User.  The sign_request method is a reusable method that associates the logged-in User with the request to HelloSign.  

In the enrollment method, the reusable sign_request method is called and given parameters specific to the enrollment form.  Then, HelloSign generates a unique ID for the signer which is passed as part of the get_embedded_object request.  The function returns the unique URL for the User’s signature.  

Display the Embedded Signature Request

If you have built your front end using Django Templates or Jinja2, you can still use HelloSign’s JavaScript client-facing Embedded Signature Request UI.

First, use npm to install the HelloSign Embedded package.  If you are not using npm, it is still possible to install it via CDN, manual download, or by compiling from the source by visiting HelloSign’s wiki.  

Then, create a file called hellosign.js to call the front-end client:

littleschool/parent_portal/hellosign.js

‍

This script, which gets the signURL variable passed from views.py, can be embedded in your HTML templates, either in the <head> or <body>.  In this case, in order to make the <script> element callable from multiple templates, we’ve opted to put it in the <head> inside base.html:

littleschool/parent_portal/templates/base.html

‍

Then, from inside the `enrollment.html` template, we call the method with an onClick function:

littleschool/parent_portal/templates/enrollment.html

‍

Get Confirmation When Documents Are Signed

It’s best to monitor completion of eSignature requests in a separate admin app.  In the case of a school, this might be the app used by just the Enrollment Director, or it could be accessible to all staff.  Either way, keep this functionality separate from the parent_portal.  

Use the signature_request_id of the desired SignatureRequest to call the HelloSign API for the current status using the Get Signature Request endpoint. If desired, those results can be sorted or filtered - for example, an administrator might want to see all kindergarten enrollment forms, or a teacher might want field trip forms for just the students in one class.  

Your admin app can follow a similar setup to the parent_portal, or you can locate the HelloSign files - hellosign.js and hellosignclient.py in a directory where both Django apps have access, perhaps determined by the scale of your admin functionality.  Either way, the calls to the HelloSign client will use the same API credential as the parent_portal methods.  

The get_signature_request endpoints, both individual and list,  will return a signature_request object, which will contain the status of each signature:

littleschool/admin/hellosignclient.py

‍

At any point during the SignatureRequest process, you can download your files to see the current version.  To do this, you’ll need to have a file management system installed in your application, like the basic PyPi file system, fs.  You can download .zip or PDF files:

littleschool/admin/views.py

‍

So long as you maintain your HelloSign account, you’ll have ongoing access to your files through the API, or you can set up your system to download them and save them locally or to a cloud drive.

HelloSign offers a great deal more functionality, and as your application scales, that functionality and Django’s flexibility will work together to deliver a seamless experience! To learn more about the HelloSign API and start testing for free, visit HelloSign’s Developer Portal