Using DocuSign for autofilling and signing documents
Using DocuSign for autofilling and signing documents
January 23, 2017
Tutorial
Front end
Development
Integration
Microservices

Using DocuSign for autofilling and signing documents

January 23, 2017
Tutorial
Front end
Development
Integration
Microservices
Mikhail
Khokhlov
Front-end developer

It’s uncomfortable when you have to do your paperwork in bulky outdoor clothes while standing or being eyed by a clerk, a bank employee or an insurance agent. Even when you fill out your documents in the comfort of your own home, there’s always a risk that you might make a mistake and have to start from scratch.

An excellent way to prevent mistakes when handling paperwork is autofilling. In this article we are going to tell you how we helped one of our clients to automate filling and signing insurance company blanks using the DocuSign service, which served to attract customers and increase customer loyalty.

What is Docusign?

Docusign is a service that allows you to upload, send for signing, look through and sign documents; as well as track document status using either the service’s own interface or a custom client (that is supposed to use API and Embedded View for viewing and signing documents).

Security

Document and electronic signature security is certified in accordance with the ISO 27001 standard that establishes the basic terms and conditions for data security systems.

All data transferred between the client and the DocuSign services is encrypted and sent using the HTTPS protocol. Documents and templates stored in DocuSign are encrypted using the AES-256 algorithm.

HIPAA Compliance

Docusign permits working with documents and e-signatures in full accordance with HIPAA (Health Insurance Portability and Accountability Act 1996). HIPAA establishes the standards of health information confidentiality (including information like physical condition, medical history and history of payment for medical services).

Getting started

Our goal is to fill out and send blanks with the help of DocuSign.

Let’s say we have to send a single PDF document to several people. We could send the file manually by e-mail, but DocuSign has a designated procedure for this which works with the following entities

  • Template. This entity includes a PDF document, the document’s tabs (fields) and the relationships between the tabs and the recipients’ roles. This means, for instance, that one signature tab can be reserved for the employee to be hired and the other for the head of the HR department (or the CEO);
  • Envelope. This entity is a container for storing and sending one or more multi-page documents.

The process of working with documents includes:

  1. Creating a Template.
  2. Sending the document to the selected recipients.
  3. Saving the finalized document.

Let’s examine each stage in detail.

Registering a sandbox

To gain access to all of the DocuSign features you have to create a demo account (a sandbox). To do this, click the Create Sandbox button in the Developers section of the DocuSign main page.

image06.png#asset:7413

After you validate your account, you can continue.

Creating a Template

To create a Template:

  1. Navigate into the Templates tab and click New -> Create Template.

  2. Enter the name and the description of the template.

image10.png#asset:7414

         3. Upload the documents.

image00_170116_135137.png#asset:7415

         4. Add recipients. If you plan on using the template repeatedly and sending it to several recipients, you can enter only the name of the role (e.g., “employee” for the company’s workers).

image08.png#asset:7416

         5. Click Next.

Afterwards, we get to the screen where we add fields to the document. In the future, only the document’s recipient will be able to fill them in. If there are several recipients, fields can be designated for each of them.

image00_170123_064820.png#asset:7442


Each field has several parameters. The Data Label parameter deserves special attention as it can be used as an identifier when working with the template or document’s data in the API. It’s also worth noting that Data Label is not a unique value, so there can be several duplicate fields with it. This comes in handy when you need to automatically fill in several fields at once with the name of the same person.

Sending a document

To send a document for the recipients to later fill out and sign, you have to click the ‘Use’ button located across the selected template. In the window that opens, enter the names and e-mails of the recipients.

image04_170123_064922.png#asset:7443After you have sent the document, the selected recipients will get notifications asking them to examine, fill out and sign the document. The e-mail will include a link to the form with the document. If there is only one recipient of the document, its status will be changed to ‘Completed’ after it’s signed, and the status change will be displayed in the DocuSign interface. The filled and signed document can then be downloaded. If there are two or more recipients, the document status will stay as it is (Sent).

Everything we have just done manually (i.e., sent the document to the required recipients and they have signed it) can be automated with the help of the API, so be sure to check out the next part.


Getting started with the API

Docusign has two API’s: SOAP and REST. We’ll use the latter in our example, as it’s more demonstrative and its method implementation is more comprehensive. The REST API allows signing documents, sending them for signing and automating document flow.

To start working with the REST API, we have to get authorized first. To do this, the API can send authorization data in a special header that must contain username, password and an Integrator Key.

First things first: let’s get an Integrator Key and then go back to making API requests.

1. Getting an Integrator Key.

Integrator Key (aka Client ID) is a unique identifier for getting access to the DocuSign API. A single account can have several keys registered to differentiate between environments and to have a specific key for each of them. Initially, new accounts don’t have a key, so we have to create one. To do this, log into your account and do the following:

  • go into DocuSign Admin

image05.png#asset:7419

  • choose API and Keys in the menu on the left

image03_170116_183600.png#asset:7424


  • click ADD INTEGRATOR KEY

image02_170116_140220.png#asset:7420

  • enter your app description

image04.png#asset:7421

  • click Add

That’s it, the key can now be found in the section called My Integrator Keys.

2. Making request for DocuSign

Each request to DocuSign has to be supplemented with a X-DocuSign-Authentication header that sends username, password and Integrator Key in JSON format. This format should only be used for integrating third party services with DocuSign. To work with client apps (e.g., on iOS), you’ve got to use OAuth.

Our first request to DocuSign will be a request to get account info. It’ll also contain the so called baseUrl, a URL that will be used for creating subsequent requests to DocuSign.

$ curl -i -H 'X-DocuSign-Authentication:
              { "Username": "developer@example.com",
                "Password": "example",
                "IntegratorKey": "00000000-aaaa-bbbb-cccc-0123456789b" }'\
          https://demo.docusign.net/restapi/v2/login_information
{
  "loginAccounts": [
    {
      "name": "Developer",
      "accountId": "9999999",
      "baseUrl": "https://demo.docusign.net/restapi/v2/accounts/9999999",
      "isDefault": "true",
      "userName": "Dev Eloper",
      "userId": "00000000-aaaa-bbbb-cccc-0123456789a",
      "email": "developer@example.com",
      "siteDescription": ""
    }
  ]
}

With the help of baseUrl and the X-DocuSign-Authentication header, we’re ready to make requests to the API.

3. Getting a Template.

Imagine you already have a template base and the easiest way to make it is through the DocuSign interface. We’ll use a template we made earlier. For our example, let’s use a personal data processing consent agreement in which we need to fill in the fields with the data on the document’s recipient.

The first thing we need to do is get the required template. We can do it if we know its identifier, which can be retrieved by going to the template’s page in your account:

$ curl -i -H 'X-DocuSign-Authentication:
              { "Username": "developer@example.com",
                "Password": "example",
                "IntegratorKey":"00000000-aaaa-bbbb-cccc-0123456789b" }'\
          https://demo.docusign.net/restapi/v2/accounts/9999999/templates/00000000-aaaa-bbbb-cccc-0123456789c

The data on the template’s tabs (or fields) is contained in the “tabs” property that pertains to the “recipients” property. This is the main thing we need to look for in the response:


{
  "recipients": {
    "signers": [
      {
        "tabs": {
          "signHereTabs": [ ... ],
          "dateSignedTabs": [ ... ],
          "textTabs": [ ... ]
        },
        "name": "",
        "email": "",
        "roleName": "employee"
      },
      {
        "name": "",
        "email": "",
        "roleName": "hr"
      }
    ],
    "agents": [],
    "editors": [],
    "intermediaries": [],
    "carbonCopies": [],
    "certifiedDeliveries": [],
    "inPersonSigners": [],
    "recipientCount": "2"
  }
}

DocuSign has seven recipient types: Agents, Carbon Copies, Certified Deliveries, Editors, In Person Signers, Intermediaries, and Signers. In our template, we’ll only be using Signers*, which is why we’ll examine only this type.

*”Signers” doesn’t necessarily mean that all of the recipients of this document have to sign it. In fact, if you don’t assign any tabs that the user has to fill (or sign), it’s enough for them to just open the document and look through it.

As was mentioned before, each recipient has a “tabs” property that contains all the tabs in the document. Tabs are divided into several types as well. We will not go into these types to save time and just pick textTabs (fields for entering text) and signHereTabs (fields for signatures). These are the two most common types of fields in documents.

Let’s move on to autofilling.

4. Filling in tabs and sending the document to the recipients.

For DocuSign to automatically fill in the required values, you have to send the list of all the recipients when creating the document. You can do so by adding the “tabs” property for the recipients for whom you want to fill in the tabs.

The tab has to contain the following properties: name, tabLabel, xPosition, yPosition and value. We have already mentioned tabLabel above, as this tab will be useful for identification. For instance, we can match the tab with the tabLabel equal to “nameFull” with the recipient’s full name and put it into the “value” property.

Our document has the following fillable tabs: nameFirst, nameLast, middleInitial, ssn, dob, email, phone, addressStreetSuite, aptNumber, city, state, и zipCode.

Let’s set values for these tabs and send the document:

nameFirst: “Emma” 
nameLast: “Erickson” 
middleInitial: “A” 
ssn: “123 45 6780” 
dob: “12/29/1987” 
email: “emma@example.com” 
phone: “+18663301515” 
addressStreetSuite: “101 Tremont St” 
aptNumber: “11” 
city: “Boston” 
state: “MA” 
zipCode: “02108”

To create a document, we’ll make the following request:

$ curl -X POST -H 'X-DocuSign-Authentication:
              { "Username": "developer@example.com",
                "Password": "example",
                "IntegratorKey":"00000000-aaaa-bbbb-cccc-0123456789b" }'\
           -d '{
                "status": "sent",
                "emailSubject": "Example",
                "templateId": "00000000-aaaa-bbbb-cccc-0123456789c",
                "templateRoles": {
                  "signers": [{
                    "name": "Emma Erickson",
                    "email": "emma@example.com",
                    "recipientId": "1",
                    "routingOrder": "1",
                    "tabs": {
                      "textTabs": [
                        {
                          "xPosition": "150",
                          "yPosition": "200",
                          "name": "First Name",
                          "tabLabel": "nameFirst",
                          "value": "Emma"
                        },
                        {
                          "xPosition": "150",
                          "yPosition": "200",
                          "name": "Last Name",
                          "tabLabel": "nameLast",
                          "value": "Erickson"
                        },
                        ...
                      ],
                    }
                  }]
                }
              }'\
              'https://demo.docusign.net/restapi/v2/accounts/9999999/envelopes/'

Our response will contain the identifier of the created document (envelopeId), the date of the last status change (statusDateTime) and the status itself (status):

{
  "envelopeId": "00000000-aaaa-bbbb-cccc-0123456789d",
  "uri": "/envelopes/00000000-aaaa-bbbb-cccc-0123456789d",
  "statusDateTime": "2016-09-27T19:52:09.7670000Z",
  "status": "created"
}

The document is filled out and sent, and the recipient doesn’t have to worry about filling in their data. Here’s how the resulting document form looks:

image07_170123_065333.png#asset:7444

Now, when we’ve created the basic functionality of the app and are ready to use it in the release version, we need to go through certification.

Certification

Certification is required to use DocuSign integration in a working environment. For certification to go smoothly, you need to make sure that your client meets the following requirements:

  1. It doesn’t use undocumented API features.
  2. It doesn’t use features you don’t have access to due to limited subscription.
  3. It doesn’t exceed allocated quota.

How to go through certification

1. Fill out and send the certification request form to the Developer Center. In the form, specify:

 Integrator Key;

  • Account ID;
  • The interval of time during which you’ll have to make no less than 20 requests to DocuSign. The requests will demonstrate how you are planning to use the API.

2. Use your app in the designated time interval and make no less than 20 transactions with DocuSign.

3. If everything is OK, you’ll be provided with a Post Certification Guide to prepare for release. Usually this process doesn’t take more than a week, but I don’t recommend doing it just before release, as documents won’t have legal effect without certification and you won’t have access to DocuSign support.

Conclusion

In this example we’ve scratched the surface of DocuSign integration and created a client for autofilling templates and sending documents for signing. I hope this knowledge will help you decide whether you’re going to use this service (perhaps with a more complex integration plan in mind) or not.

Our other articles

This article is an introduction to iOS app animation. It will be helpful for those who haven’t had the chance to work with animations yet or don’t fully comprehend some aspects of standard iOS animations.

Reflections about the future, in which websites load quickly and run smoothly, and how to approach it.

Mikhail
Mikhail
Khokhlov
Front-end developer