.net, Digital Signature

Integrate DocuSign with a C# MVC Website

Last time, I wrote about digital signatures, how to set up DocuSign to manage digitally signing documents, and wrote some C# code to allow this DocuSign process to be built into a custom C# application.

This time I want to write about how to integrate this with a .NET MVC website.

I’d normally use .NET Core these days – however, the DocuSign SDK is written for the .NET Framework so I’ll use that. If your website is already in .NET Core, it would be possible to put the DocuSign functions into a .NET Framework RESTful API, and then access this API from a .NET Core MVC site.

I created the baseline MVC application using Visual Studio 2017 (and I’ve pushed the finished code to GitHub here).

My intention is to customise this to show:

  • A list of documents which have been generated with my profile, and their statuses, and
  • A page for a user to enter in a name and an email address, and generate a document.

Create a class to list the DocuSign envelopes my profile has sent.

This is straightforward (when you know how!) – you can list envelopes using the ListStatusChanges method of the EnvelopesApi object. If we know profile’s Account Id, we can specifiy options (such as the number of envelopes to return, and the earliest envelope date we’re interested in) and use these options to list the envelopes sent.

var fromDate = DateTime.UtcNow;
fromDate = fromDate.AddDays(-30);
string fromDateStr = fromDate.ToString("o");
// set a filter for the envelopes we want returned using the fromDate and count properties
var options = new EnvelopesApi.ListStatusChangesOptions()
        count = numberOfItems.ToString(),
        fromDate = fromDateStr
EnvelopesApi envelopesApi = new EnvelopesApi();
return envelopesApi.ListStatusChanges(accountId, options).Envelopes;

I put this code into a class named DocuSignProfile and a method called ListEnvelopes – you can see the complete file at GitHub here.

This makes it very easy to get a list of 10 Envelopes in my controller and pass them to the view, as shown below (the GetDocuSignCredentials() method just gets an object with my username, password and integrator key – you can see the details in the source code.).

public ActionResult Index()
    var myProfile = new DocuSignProfile(GetDocuSignCredentials());
    return View(myProfile.ListEnvelopes(10));

The project now shows this table on the home page, as shown below. You can see the items which have been digitally signed and returned with the status “completed” – the other documents which have been sent but the recipient hasn’t signed yet have the status “sent”.


When I click on the “Create a Document” button, it takes me to a page which allows me to enter a name and email address.


When I enter a name and email, and then click on Generate Document, it sends an email to the address specified on the page above with a request to sign a digital document.I’ve described the process of how a recipient signs a document here, so I won’t repeat it again in this post.

The code at GitHub is proof-of-concept and follows a happy path, it isn’t robust and won’t handle errors well (like leaving fields blank) – it’s just intended to be the bare minimum example code needed to demonstrate how to integrate DocuSign with a website.


In the last couple of posts, I’ve written about how to use DocuSign to generate documents to be digitally signed by a recipient, and how to integrate this off-the-shelf solution with a C# MVC website. I hope this helps anyone working with DocuSign and C#.

I’ve pushed the source code to my GitHub repository here. All passwords and keys should be stored in the web.config file (I’ve deleted my keys obviously).

.net, Digital Signature

Digitally signing documents with Docusign and integrating with C#

I’ve recently been asked by a few people about “digital signatures” – specifically in the context of projects digitising a paper process where a person normally scrawls their John Hancock on a paper form to confirm they’ve read it or processed it in some way.

There’s a lot to digital signatures – it’s much more than just replicating an image of a person’s traditional wet signature made with a pen and paper. This is easy to forge – digital signatures attempt to solve this. Recipients of the signed document need to believe the document is three things:

  • Authentic – we are sure who sent it, and trust this person.
  • Unaltered in transit – we must trust that the document has not been modified between being sent by one party and received by another.
  • Non-repudiable – the sender cannot later claim to have not signed the document.

One of the first rules of security is “don’t hand roll your own implementation“, so I’ve been looking out for implementations which I can integrate with websites using C# on the server. One matching implementation is offered by DocuSign.

So let’s take a very simple case – I want to be able to enter in a person’s name and email on a website, and have a document sent to them automatically for them to “digitally sign”. So:

  • I open a page on a corporate intranet, enter in a person’s name and email, and then click Submit.
  • At this point I’d like a document to be sent to this person.
  • This person would receive a document with an invitation to sign it.
  • The person signs the document, and I receive a notification the document has been signed.

You can do this with the DocuSign site directly – but you might want to integrate these steps as part of a custom workflow in your own site without having to break the process to go to the DocuSign site. Fortunately DocuSign provide an open-source C# client which allows you to integrate the digital signature workflow into your website application.

I’ll run through the steps needed to do all of this. The first part of this post is going to spend a lot of time talking about how I set up things on the DocuSign site, and the later part is going to focus on C# integration a lot more.

I don’t work for DocuSign, nor am affiliated with them in any way – this is just a post on how to use this commercial product to digitally sign documents.

First, set up your DocuSign account

You can get a free developer account with DocuSign – you just need to give your name and email, and then select a password.


After you’ve done this, you’ll be sent an email with a link – click the link to activate your account.


Once you’ve set up your account, you’ll be able to see the account home page, like the image below.


Next, set up your documents and templates

Let’s say there’s a standard MS Word document that I want to use – it could be a contract, or almost anything that a standard paper based process would have for people to print off and sign with a pen. For the purposes of this example, I’ve created a simple dummy Word document (shown below).


I’ll continue to use that document for this example.

I’ll describe the next part in detail as there are some very specific steps to take- to follow the document generation process described in the paragraph above, you need to create a Template. You can start this process by clicking on the “Templates” item in the top navigation menu….


….and from the window that opens, click on the “Create One” button.


This will take you to the page where you can create your template.

  • I’ve given my template the name “Dummy Template”
  • I’ve also added a recipient role of “Test Email Recipient”. I haven’t specified a name or email, and I’ve left the default action as “needs to sign”.
  • There can be lots of recipient roles (for example, a document might need a number of people to sign it before a process can continue) – so remember that even though this unique template has a single role, it’s really a list with just one item in it. This bit is important to remember later when I write some C# code.


Next, in the Add Documents section of the page shown above, I clicked on the blue “Upload” button and a standard dialog opens which allows me to select a document. I browsed to the dummy MS Word document I created earlier, and selected to upload this.


The image above shows what this section looks like after I’ve uploaded the document. Following this, I click on the yellow “Next” button in the top right of the screen.

The next screen that appears shows a preview of the document I uploaded, with some standard fields listed on the left hand side.


I can drag the standard fields from the left hand menu onto the document preview. In the image below, you can see I’ve dragged three items:

  • One to indicate where I want the recipient to sign the document,
  • One which is automatically pre-populated with the recipient’s name, and
  • One which is automatically pre-populated with the date the document was digitally signed.


After I added these fields, I hit the “Save and Close” button in the top right of the screen.

I now have a template which contains a document that email recipients can digitally sign, and I’ve described the role of the recipient as “Test Email Recipient”.

This for a real business case, this role might be more usefully named as “Future Employee” or “Approver”.

Next, test your template and document through the DocuSign website

Now that we have uploaded a document, and configured it for digital signatures, we can test how this will appear to our end users through the DocuSign website.

From the DocuSign home page, click on the yellow “New” button and select “Use a template”.


This opens a dialog like the one below, which lists the templates I’ve created. I click on “Dummy Template” to use it.


When it opens, I enter in the name and email address of the person I want to send a document to for them to digitally sign it. I can also enter a custom email subject line and a customised email message. Then I click the blue “Send” button.


Pretty soon afterwards, I receive an email in my inbox like the one below, inviting me to review a document and sign it.


If I click on the “Review Document” button, my browser opens showing the document associated with the template, and I just need to click on the button saying “Sign” to digitally sign the document.


When I click the button, there’s a dialog opens which shows you how the signature will be rendered. I’m not really sure of the point of this part – this might just be to help users feel a bit more comfortable with something that looks like a signature.


Once you’ve selected a signature to adopt, we’re returned to the document with a preview of what the document will look like, and I can click the yellow “Finish” button in the top right to finish the process, and send the document back to the originator.


So if I go back to my DocuSign home page, I can see that there’s now a number 1 beside the number of completed documents in the overview section.


And if I click on the Completed section, I can drill in to get a detailed list of these completed documents, as shown below.


I can click on this row to see the details of when the document was signed, and I can actually see a copy of the signed document.

Now I’ve tested my template and seen an email delivered to my address, I’ve digitally signed the document associated with that email, and in my DocuSign account I can see that the document was signed.

Next, integrate this process with C# and an application

Let’s say I want to trigger this process from my own website rather than having to trigger it from the DocuSign website. Fortunately this is pretty easy, because DocuSign have a C# SDK which is available on GitHub here. They provide some helpful sample code which I’ve used to get me started, but I’ve made some changes for this post which I think make the interactions a little clearer.

In this post I’ll go as far as create a C# class to generate a document for digital signature, and I’ll test it using a console application. It’ll be pretty easy to use and instantiate this class in a website.

Generate an Integrator Key

To integrate DocuSign with my web application, I need to generate an “Integrator Key”. To do this, I open up the admin screen – I can access this from my DocuSign home page using the menu shown below.


In the admin screen, click on the “API and Keys” item under the “Integrations” menu on the left hand side. This will open a screen called “API and Integrator Key Information”.


Click on the “Add Integrator Key” button to open up the dialog shown below. I added the app description of “Dummy Client Application”, and click on “Add”.


When you click “Add”, the integrator key is created, and is listed as shown in the screen below (again I’ve covered my API keys with a grey strip to keep them secret).


Create an object representing the DocuSign template

Our template above contained a single role – “Test Email Recipient”, but it actually could have contained a number of roles (e.g. “First Approver”, “Second Approver” etc.).

I’ve written a custom object which accepts a couple of parameters in the constructor:

  • The unique Id for the template (this is a string, but looks a lot like a GUID)
  • A list of role names belonging to that template – so in our example case, it would be a list of strings with a single item in the list of “Test Email Recipient”.
public class DocuSignTemplate
    public DocuSignTemplate(string templateId, IList<string> templateRoleNames)
        this.TemplateId = templateId;
        this.TemplateRoleNames = templateRoleNames;
    public IList<string> TemplateRoleNames { get; set; }
    public string TemplateId { get; set; }

If you want to obtain the Id for a template, you can copy it from the DocuSign site at the page below (I’ve blanked the actual template Id out and replaced it with a grey strip below).


So if I wanted to use this for a template with a GUID and a role of Test Email Recipient, my code might look like this:

var docuSignTemplate = new DocuSignTemplate("e6a4919d-3a05-41e1-8b83-313ea467093e", new List<string> { "Test Email Recipient" });

Create an object for the customised email message

Another thing which we can manage from our code is the content of the email message sent to the document recipient – I’ve created a simple object for this email, which allows me to pull the subject and message body from configuration (this might seem a bit unrelated to the nature of this post but it’ll be obvious why I’m doing this in a little while).

public class EmailTemplate
    public EmailTemplate(string subject, string messageBody)
        this.Subject = subject;
        this.MessageBody = messageBody;
    public string Subject { get; set; }
    public string MessageBody { get; set; }

So if I want to instantiate this with a custom subject line and message for my email, I could write the code below:

var emailTemplate = new EmailTemplate("[DocuSign C# SDK] - Sample Signature Request", "Hello this is the email message.");

Create a class to generate the document and send the email

After looking at the code on DocuSign’s GitHub account here, I tried to do a little refactoring to make the code a bit more object oriented and re-useable.

I created a simple object to take the credentials required to access my DocuSign account – username, password and integratorKey.

public class DocuSignCredentials
    public DocuSignCredentials(string username, string password, string integratorKey)
        this.Username = username;
        this.Password = password;
        this.IntegratorKey = integratorKey;
    public string Username { get; set; }
    public string Password { get; set; }
    public string IntegratorKey { get; set; }

So if I wanted to use this, I could instantiate this object with the code below.

var docuSignCredentials = new DocuSignCredentials("jeremylindsay@myemail.com", "[password]", "e84d056e-5644-4bc5-b880-b1668e1b7dcb");

Next, I’ve refactored the sample code presented by DocuSign to create a class named DocuSignDocumentGenerator This class’s constructor takes parameters of the credentials required to log in, the details of the email template and custom message, and the details of the DocuSign template we want to use.

You’ll need to search for the DocuSign.eSign package on NuGet and install this into your C# project as well.

public class DocuSignClient
            public DocuSignClient(DocuSignCredentials credentials)
                // initialize client for desired environment (for production change to www)
                var apiClient = new ApiClient("https://demo.docusign.net/restapi");
                // configure 'X-DocuSign-Authentication' header
                var authHeader = "{\"Username\":\"" + credentials.Username + "\", \"Password\":\"" + credentials.Password + "\", \"IntegratorKey\":\"" + credentials.IntegratorKey + "\"}";
                Configuration.Default.AddDefaultHeader("X-DocuSign-Authentication", authHeader);
                // login call is available in the authentication api 
                var authApi = new AuthenticationApi();
                var loginInfo = authApi.Login();
                // parse the first account ID that is returned (user might belong to multiple accounts)
                this.AccountId = loginInfo.LoginAccounts[0].AccountId;
            public string AccountId { get; set; }
        public class DocuSignDocumentGenerator
            public DocuSignDocumentGenerator(DocuSignCredentials credentials, EmailTemplate emailTemplate, DocuSignTemplate docuSignTemplate)
                this.DocuSignCredentials = credentials;
                this.EmailTemplate = emailTemplate;
                this.DocuSignTemplate = docuSignTemplate;
            public DocuSignCredentials DocuSignCredentials { get; set; }
            public EmailTemplate EmailTemplate { get; set; }
            public DocuSignTemplate DocuSignTemplate { get; set; }
            public void GenerateDocument(string name, string email)
                var docuSignClient = new DocuSignClient(this.DocuSignCredentials);
                var accountId = docuSignClient.AccountId;
                // assign recipient to template role by setting name, email, and role name.  Note that the
                // template role name must match the placeholder role name saved in your account template.  
                var templateRoles = this.DocuSignTemplate.TemplateRoleNames.Select(m => new TemplateRole
                    Email = email,
                    Name = name,
                    RoleName = m
                // create a new envelope which we will use to send the signature request
                var envelope = new EnvelopeDefinition
                    EmailSubject = this.EmailTemplate.Subject,
                    EmailBlurb = this.EmailTemplate.MessageBody,
                    TemplateId = this.DocuSignTemplate.TemplateId,
                    TemplateRoles = templateRoles,
                    Status = "sent"
                // |EnvelopesApi| contains methods related to creating and sending Envelopes (aka signature requests)
                var envelopesApi = new EnvelopesApi();
                var envelopeSummary = envelopesApi.CreateEnvelope(accountId, envelope);

So to use this class, I’d call it like this:

var documentGenerator = new DocuSignDocumentGenerator(docuSignCredentials, emailTemplate, docuSignTemplate);

And to generate a document, I’d use code like the snippet below:

static void Main(string[] args)
    var emailTemplate = new EmailTemplate("[DocuSign C# SDK] - Sample Signature Request", "Hello this is the email message.");
    var docuSignTemplate = new DocuSignTemplate("4a48d276-8faa-45b7-9957-d73538a616cc", new List<string> { "Test Email Recipient" });
    var docuSignCredentials = new DocuSignCredentials("jeremylindsay@testemail.com", "[my password]", "e9e6caf1-b3d3-4294-b057-75fdf7367941");
    var documentGenerator = new DocuSignDocumentGenerator(docuSignCredentials, emailTemplate, docuSignTemplate);
    documentGenerator.GenerateDocument("J. Lindsay", "jeremy.lindsay@recipientdomain.com");

This is in the main method of a console application which is how I found to be the easiest way to test my code – but I could use this just as easily in my custom website.


In this post I’ve described a lot of things:

  • How to sign up for a developer account at DocuSign
  • How to create a template and configure a document to be digitally signed
  • How to test this template through the DocuSign website
  • How to create an Integrator Key for an application to directly integrate with the DocuSign REST API
  • How to use C# to integrate a console application with this DocuSign class

In another post I’ll describe how to integrate a C# MVC website with this class to generate documents.