How to fill out and sign documents automatically using DocuSign

We do it standing. In winter clothes. Under the watchful eye of an official, a bank employee or an insurance service. Even if you do it at home with comfort, there is a risk of making a mistake and starting over. I'm talking about working with paper documents, because most often it happens that way.



Automation of filling helps to avoid such errors. In this article, I’ll tell you about how one Taiping client helped automate the filling and signing of insurance company forms using the DocuSign service. After its introduction, the number of customers and their loyalty increased.

What is DocuSign?

DocuSign is a service that allows you to download, send for signature, view, sign and track the status of documents. This can be done both from the service interface, and with the help of a native client, which must use the API and Embedded View to view and sign documents.

')

Legal status

DocuSign can work with both facsimile and digital signatures. If you plan to work in the western market, then there should be no problems with this. In Russia, you need to consider the use of facsimiles is determined by law or by special agreement of the parties. There are a number of cases in which you cannot use facsimiles. In more detail about it it is possible to read on the Garant portal .

Security

The security of documents and electronic signatures is certified in accordance with ISO 27001, which defines the basic provisions in the field of information security systems.

All data between the client and the DocuSign services are transmitted in encrypted form over HTTPS. Documents and templates that are stored in DocuSign are encrypted using the AES-256 algorithm.

HIPAA Compliance

DocuSign allows you to work with documents and electronic signatures in full compliance with the HIPAA (Health Insurance Portability and Accountability Act, or the US Law on Transportability and Accountability of Health Insurance, published in 1996). The law defines standards for ensuring the confidentiality of health information: health status, treatment or payment for medical services.

Beginning of work

Our goal is to fill out and submit forms using DocuSign.



Suppose we need to send the same PDF document to different people. We could send it by mail manually, but there is a special mechanism for this in DocuSign. The mechanism operates with the following entities:

• Template. An entity encapsulates a PDF document, document fields, and relationships between fields and recipient roles. This means that one field with a signature can be for a hired employee, and another for a head of personnel department or director;
• Envelope. Container for storing and sending one or more multi-page documents.

The process of working with documents consists of:

1. create a template;
2. sending the document to selected recipients;
3. save the final document.

We will analyze each step separately.

Register demo account

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







It remains to confirm your account, and we are ready to go further.

Creating a template

To create a template:



1. Go to the Templates tab and click New -> Create Template;

2. Enter a name and description for the template:







3. Download documents:







4. Add recipients. To reuse and send the template to different recipients, you can specify only the name of the role (for example, employee for the role of company employees):







5. Click Next.



After that we will get to the screen of adding fields to the document, which the recipient will be able to fill in later. If there are multiple recipients, fields can be assigned to each of them.







Each field has a number of parameters. On the parameter Data Label is to focus your attention. It can be used as an identifier when working with data from a template or document through an API. It is worth noting that Data Label is not a unique value, so fields with it can be duplicated. This is useful if you need to automatically fill in several fields at once with the name of the same person.

Sending document

To send a document to recipients who then fill it out and sign it, you must click on the Use button next to the selected template. After that, a window will open in which you need to enter the names and emails of the recipients:







After you send the document, the selected recipients will receive a notification asking them to verify, complete and sign the document. The letter will link to the form with the document. If this document has only one recipient, then after signing, its status will be replaced with Completed, which will be visible in the DocuSign interface. After that, the completed and signed document can be downloaded. If there are two or more recipients, the status of the document will remain the same (Sent).



All that we have now done manually (sent the document to the right recipients, and the recipients filled it out) can be done automatically using the API. This will be discussed in the next section.

Getting started with the API

DocuSign has two APIs: SOAP and REST. We will consider the second option, since it is more obvious and also contains the most complete implementation of the methods. REST API allows you to sign documents, send documents for signature, as well as automate workflow.



To work with the REST API, we need to log in. For these purposes, the API has added the ability to transfer data for authorization in a special header, which should contain a user name, password, as well as an Integrator Key.



For a start, let's figure out how to get the Integrator Key, and then back to composing requests to the API.

Get Integrator Key

Integrator Key (also Client ID) is a unique identifier for accessing the DocuSign API. For one account can be registered several such keys. This is done in order to share the environment and use their own key for each of them. Initially, there are no keys in new accounts, so you have to create it. To do this, you need to log into your account and complete these steps:



1. Go to DocuSign Admin:







2. In the left menu, select API and Keys:







3. Click ADD INTEGRATION KEY:







4. Add a description of the application:







5. Click Add.



Is done. The key can now be found in the My Integrator Keys section.

Create Requests for DocuSign

Each request to DocuSign should be accompanied by the X-DocuSign-Authentication header, where the user name, password and Integrator Key are transmitted in JSON format. This format should only be used to integrate third-party services with DocuSign. To work with client applications (for example, with an application on iOS), you must use OAuth.



Our first request to DocuSign should be a request for account information. There will also be the so-called baseUrl - url, which should be used to compose 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": "" } ] } 

Armed with baseUrl and the X-DocuSign-Authentication header, we are ready to make requests to the API.

Getting a template

Suppose that you already have a template database, which is easiest to do through the DocuSign interface. We will use a template that has already been created. As an example, take the consent to the processing of personal data, in which we need to fill in the fields with data about the recipient of the document.



The first thing we need to do is get the desired template. We can do this if we know its ID. The ID can be obtained by going to the template 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 for the template fields is contained in the tabs property, which belongs to the recipients property. Of all the answer, we are interested in it now:

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

There are seven types of recipients in DocuSign: Agents, Carbon Copies, Certified Deliveries, Editors, In Person Signers, Intermediaries, and Signers. In our template, we use only Signers *, so we will consider only this type.



* With its name, this type indicates that its recipients must sign the document. This is not at all necessary: ​​if you do not assign the user the fields to fill out (or sign), then it will be enough for him to open the document and view it.



As mentioned above, each recipient has a tabs property, which contains all the fields in the document. Fields are divided into several types. We will not consider all of them and in order to save time, we take only textTabs (text input fields) and signHereTabs (signature fields). These are the two main fields that are most often found in documents.



Let's go to autocomplete.

Filling the fields and sending the document to recipients

In order for DocuSign itself to substitute the necessary values, when creating a document, you must pass a list of all recipients by adding the tabs property for recipients with which you want to fill in the fields.



The field must contain the properties name, tabLabel, xPosition, yPosition, as well as the value of the input field value. We have already spoken about tabLabel above - this field will be useful to us for its identification. For example, with a field with a tabLabel equal to nameFull, you can uniquely match the full name of the recipient and add it to value.



Our document has fields to fill in: nameFull, idNumber, idIssuedBy, idType and addressFull.



Set the value for these fields and send the document:



nameFull: “Ivan Petrov”

idNumber: “1234 567890”

idIssuedBy: “ATC”

idType: “passport”

address Full: “Moscow Avenue, 12, apt. 221 ”



To create a document, run this query:

 $ 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": " ", "email": "ivan@email.com", "recipientId": "1", "routingOrder": "1", "tabs": { "textTabs": [ { "xPosition": "150", "yPosition": "200", "name": "Full Name", "tabLabel": "nameFull", "value": " " }, ... ], } }] } }'\ 'https://demo.docusign.net/restapi/v2/accounts/9999999/envelopes/' 

The 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 and sent, and the recipient does not need to worry about entering their data on their own. This is how the form of filling out the document looks like

Certification

Certification is required so that you can use DocuSign integration in a production environment. In order for the certification process to pass without a hitch without a hitch, it is necessary that your client meets the following requirements:



1. do not use undocumented API features;

2. do not use features to which you do not have access due to subscription restrictions;

3. not to go beyond the allocated quota.

What to do to get certified?

1. Fill out and submit a certification request form in the Developer Center, in which you specify:

• Integrator key
• Account ID
• The time interval for which you will need to perform at least 20 requests to DocuSign. Requests will reflect how you plan to use the API.

2. Use your application in the selected time interval, make at least 20 transactions with DocuSign.



3. If everything is in order, then you will receive a Post Certification Guide to prepare for release. Usually this process takes no more than a week, but I do not recommend doing it just before the release - without certification, the documents will not have legal force, and you will not have access to the support of DocuSign.

Conclusion

In this example, we considered the integration features with DocuSign as superficially as possible, and also created a client to auto-fill templates and send documents for signature. I hope that this knowledge will be enough for you to understand whether to use the service and think about more complex integration or not.