Building a White Labeled eSignature Flow Using .NET Core and the HelloSign API

"Building a White Labeled eSignature Flow Using .NET Core and the HelloSign API" header image

Microsoft’s .NET Core framework is popular with developers creating data management systems for organizations of all sizes.  The MVC architecture and Entity Framework are well-adapted to maintaining scalable databases with robust built-in User profiles and authentication.

Many such organizations also need to manage large volumes of documents, as well.  HelloSign is an excellent option for C#/.NET developers looking to integrate eSignatures into their applications to meet those needs.

In this guide, we’ll show how HelloSign’s embedded SignatureRequests and white-labeling options could be used to manage contracts and waivers for an athletic league. Let’s call it Company Inc.—and let’s see how to integrate HelloSign into a new .NET project.


To learn more about the HelloSign API, visit the HelloSign Developer Portal and start testing for free (no credit card required).


Set Up HelloSign In Your .NET Core Project

We created a database management application for Company Inc. with `dotnet new mvc`, using Pomelo to handle the MySQL connection.


Once you have created your .NET project folder, install the HelloSign NuGet package by entering `dotnet add package hellosign` in your CLI.


Before you begin integrating HelloSign into your application, you’ll need to create a HelloSign account. After creating your account, go to “My Settings” and navigate to the API tab on your dashboard. There, you’ll find your API key. You will also need to create a HelloSign API App. To do that click on “Create” in the API Apps section.  Give your API App a name and a domain. As long as you are in the testing phases of development, you can ignore the domain verification fields, as those are only required for production applications. Once you add your App, you will get a Client ID specific to this project.  


Save both your API key and Client ID in your project:

Keys.cs

  
    namespace CompanyInc{
      public class Keys
      {
        public static string APIKey = "YOUR API KEY HERE";
        public static string ClientID = "YOUR CLIENT ID HERE";
      }
    }
  

Be sure to add the file to your .gitignore file to keep these secrets out of source control.

Create Entity Relationships for SignatureRequests

Anytime you create a .NET project with the Entity Framework, you need to think through how you’ll map objects in your code to your database. Even though HelloSign handles our signature requests, we’ll need to store some details on our side so we can track progress. Entity Relationships will help here, but first we need to look at what to expect from HelloSign.


HelloSign provides developers two primary options to use the API:

  1. Have HelloSign generate emails to Signers with your documents linked
  2. Embed SignatureRequests directly in your application


The second option, which we’ll show in this tutorial, keeps the entire signing and review process on your website and displays SignatureRequests in an <iFrame>  HTML element.  This creates a seamless experience for your users and allows developers to write functions for administrators to assign and monitor SignatureRequests from inside the user database.


For Company Inc., we are managing data with Entity Framework. Using HelloSign’s embedded SignatureRequests means we only need to store a single data point for each SignatureRequest in our Model.  The SignatureRequestID will give us quick access to the SignatureRequest object as required. The Entity Relationship Diagram below shows how SignatureRequests are tracked in the database.

Image of an Entity Relationship Diagram that shows how SignatureRequest objects are tracked in the database


The signed Documents needed for a particular Athlete are determined by what Teams they are a part of. Each SignatureRequest is associated with a single Athlete and single Document.

Create Methods for Your HelloSign Model to Send, Sign, and Track SignatureRequests

The HelloSign API includes endpoints for a wide range of functions.  At the most basic, your application will send a SignatureRequest, obtain a unique URL to each signer to be embedded, and retrieve the SignatureRequest to check the status and review signatures.


We chose to keep all of the API calls together as properties of the `HSeSignature` model, and dispatch them all from a single controller.  The `CreateEmbeddedSignatureRequest` method takes a specific Athlete and Document as parameters, and uses properties of these particular Entities to create the SignatureRequest object.  These can be passed in through the Controller via the ViewBag or as the Application User if you are using Identity.


Models/HSeSignature.cs

  
    namespace CompanyInc.Models
    {
      public class HSeSignature
      {
        public string HSeSignatureId {get; set;}
        public string SignatureRequestID {get; set;}
        public string DocumentId {get; set;}
        public Document Document {get; set;}
        public string AthleteId {get; set;}
        public Athlete Athlete {get; set;}
        public static Task CreateEmbeddedSignatureRequest(Document document, Athlete athlete)
        {
          var client = new HelloSign.Client(Keys.APIKey);
          var request = new HelloSign.SignatureRequest();
            request.Title = document.Title;
            request.Subject = document.Subject;
            request.Message = document.Message;
            request.AddSigner(athlete.Email, athlete.FirstName);
            request.AddCc("manager@companyinc.com");
            request.AddFile(document.Filepath);
            request.TestMode = true;
          var response = client.CreateEmbeddedSignatureRequest(request, Keys.ClientID);
          return Task.FromResult(response);
        }
        public static Task GetSignURL(HSeSignature signatureRequest)
        {
          var client = new HelloSign.Client(Keys.APIKey);
          var response = client.GetSignUrl(signatureRequest.SignatureRequestID);
          return Task.FromResult(response); 
        }
        public static Task GetSignatureRequest(HSeSignature signatureRequest)
        {
          var client = new HelloSign.Client(Keys.APIKey);
          var response = client.GetSignatureRequest(signatureRequest.SignatureRequestID);
          return Task.FromResult(response);
        }
      }
    }
  

Controllers/HSeSignaturesController.cs

  
    using Microsoft.AspNetCore.Mvc;
    using CompanyInc.Models;
    namespace CompanyInc.Controllers
    {
      public class HSeSignaturesController : Controller
      {
        [HttpPost]
        public IActionResult AssignSignatureRequest()
        {
          var document = ViewBag.Document;
          var athlete = ViewBag.Athlete;
          HSeSignature.CreateEmbeddedSignatureRequest(document, athlete);
          return RedirectToAction("ManageDocuments");
        }
        public IActionResult SignDocument(HSeSignature signatureRequest)
        {
          var signURL = HSeSignature.GetSignURL(signatureRequest);
          return View(signURL);
        }

        public IActionResult ReviewSignatureRequest(HSeSignature signatureRequest)
        {
          var signatureObject = HSeSignature.GetSignatureRequest(signatureRequest);
          return View(signatureObject.Status);
        }
      }
    }
  

Integrate HelloSign’s Embedded SDK as a Script

The embedded signing experience for the User happens entirely on your site, so you can create Views around the workflow that is best for your users. The HelloSign Embedded package is available as a Node package, but because working with npm in .NET can be difficult, we’ve chosen to import the package through the CDN. Either way, developers have access to a range of different functions within the Embedded flow.


By default, the CDN will attach itself to the Window object since it creates an <iFrame> element. Since JavaScript can’t access the Client ID from the .NET namespace, you will also need to save your Client ID in a .env file.


hellosign.js

  
    const client = new window.HelloSign({
      clientId: `${process.env.HS_CLIENT_ID}`
      });
    
    const clientSign = () => {
      client.open(signUrl);
      testMode: true;
    }  
  

Once you’ve created the embedded client script, you should embed it as a <script> inside the <head> of your html.  For Company Inc., we created an `_HSLayout.cshtml` file separate from the shared `_Layout.cshtml` View, so that the HelloSign script is only included in the <head> in Views where it will actually be used.  Otherwise, the two layout files are the same.


Views/Shared/_HSLayout.cshtml

  
    //...
    <head>
      <script src= "https://cdn.hellosign.com/public/js/embedded/v2.10.0/embedded.production.min.js"></script>
    </head>
    //...
  

Any View using this layout will be able to call the methods in `hellosign.js`.  For example, the `SignDocument` View created above by the `HSeSignaturesController` uses this layout and script:


Views/HSeSignatures/SignDocument.cshtml

  
    @{
      Layout = "_HSLayout";
    }
    @model CompanyInc.Models.HSeSignature;
    <input type="button" onclick="clientSign()" value="Sign Forms">
  

Clicking the button will open an <iFrame> element with the Document passed in through the Controller, allowing the Athlete to sign forms while still on the Company Inc. website.


Use White Labeling to Create an On-Brand User Experience

Once you have created an Embedded SignatureRequest flow in your application, you can further customize it with HelloSign’s white labeling options. You can customize the colors of text, background, buttons, and hover effects to match your website’s color scheme, giving users a more cohesive signing experience.


Once white labeling options have been set for your API App, they will remain in place unless you change them. For most applications, it makes sense to do this with a Curl request to update your app once other functionality is fully in place.


For Company Inc. and other organizations managing many users with many eSignature needs, HelloSign Embedded Signing is a great fit. It offers a straightforward, reliable way to integrate SignatureRequests with your other data and gives your users the smooth, consistent experience they expect—while ensuring you get the signatures needed to satisfy your legal team.


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.
true