For one of our enterprise clients, we built a custom solution for document generation. Its architecture was based on microservices, and a separate microservice allowed users to sign documents electronically. Using REST API, we integrated the solution with DocuSign, one of the most popular electric signature providers. Read on to find out how we did it.
What is an electronic signature?
Let us start with the explanation of what an electronic signature is and what the various types are.
An electronic signature is simply data in electronic form associated with or attached to other electronic data, such as a PDF document, and used by the signer. These data can be generated in multiple ways, providing different levels of trust in the signing entity.
The current European Union regulation “eIDAS” defines the following types of electronic signatures:
- Simple Electronic Signature: This basic version of an electronic signature does not require user authentication or identity verification. To use it, one needs to know the signer’s email address or send them a unique code before signing. It is commonly used in standard agreements such as sales, NDAs, or on invoices.
- Advanced Electronic Signature: This type of signature must meet specific requirements, such as being uniquely linked to the signer, allowing the signer to be identified, being created using means under the signer’s sole control, and being connected to the signed data in a way that detects any changes.
- Qualified Electronic Signature: This signature type must comply with a country’s government specifications and be issued by the government or a related institution. Obtaining it requires identity verification, e.g., using an ID card. This signature is equivalent to a handwritten one.
As for legal requirements regarding electronic signatures, they vary significantly between countries. DocuSign offers a comprehensive guide outlining what to expect in different locations. It is worth noting that there are use cases where electronic signatures, even qualified ones, cannot be used, such as notarial processes or documents requiring a manual signature.
Leveraging DocuSign eSignature API for document signing
To access DocuSign’s features, you can use the eSignature REST API. When starting to work with the system, it is helpful to familiarize yourself with the usage examples generated for your account and programming language of choice. These examples serve as an excellent knowledge source for quickly launching your project, showcasing the entire document signing process and providing relevant code snippets.
The process of using the API consists of the following steps:
- Obtain an OAuth token: The API offers several well-documented authentication methods. In our case, we chose the JWT Grant method.
- Create an envelope definition:
EnvelopeDefinition env = new EnvelopeDefinition();
env.EmailSubject = "Please sign this document set";
string docPdfBytes = Convert.ToBase64String(docPdf);
Document document = new Document
{
DocumentBase64 = docPdfBytes,
Name = fileName,
FileExtension = "pdf",
DocumentId = "1"
};
env.Documents = new List<Document> { document };
Signer signer = new Signer
{
Email = signerEmail,
Name = signerName,
RecipientId = "1",
RoutingOrder = "1"
};
CarbonCopy cc = new CarbonCopy
{
Email = ccEmail,
Name = ccName,
RecipientId = "2",
RoutingOrder = "2"
};
SignHere signHere = new SignHere
{
AnchorString = "Podpis",
AnchorUnits = "pixels",
AnchorYOffset = "10",
AnchorXOffset = "20"
};
Tabs signerTabs = new Tabs
{
SignHereTabs = new List<SignHere> { signHere }
};
signer.Tabs = signerTabs;
Recipients recipients = new Recipients
{
Signers = new List<Signer> { signer },
CarbonCopies = new List<CarbonCopy> { cc }
};
env.Recipients = recipients;
env.Status = envStatus;
At this stage, we define all information related to the document being signed. To do this, we create an EnvelopeDefinition object and include the document for signing, details about the signers and those involved in the process, as well as the locations where the document should be signed. In this case, we can see the use of the AnchorString property, which allows the DocuSign
API to automatically search for appropriate locations in the document based on specific keywords. In our example, a signature box will appear wherever the word “Signature” is found.
- Sending the Envelope: Once the data is prepared, we send it to the appropriate API endpoint, including the token obtained in the first step in the header.
EnvelopeDefinition env = MakeEnvelope(signerEmail, signerName, ccEmail, ccName, docPdf, fileName, envStatus);
var apiClient = new ApiClient(basePath);
apiClient.Configuration.DefaultHeader.Add("Authorization", "Bearer " + accessToken);
EnvelopesApi envelopesApi = new EnvelopesApi(apiClient);
EnvelopeSummary results = envelopesApi.CreateEnvelope(accountId, env);
return results;
- Upon receiving a response, we obtain the envelope ID, which we save to our local database. This allows us to monitor the status of the sent documents effectively.
var envelope = docuSignHelper.SignDocumentWithEmail(context.Message.Username, context.Message.Email, context.Message.FileContent, context.Message.Filename);
logger.LogInformation($"A request has been sent for the signature of a document with id ({context.Message.Id})");
var localEnvelope = new Domain.Entities.Envelope(Guid.Parse(envelope.EnvelopeId), envelope.Uri, DateTime.Parse(envelope.StatusDateTime), envelope.Status, context.Message.Id, context.Message.Email, context.Message.Username, context.Message.FileContent, context.Message.Filename, context.Message.FileType);
envelopeRepository.AddEnvelope(localEnvelope);
logger.LogInformation($"A document was saved to the database with id ({context.Message.Id}), envelopeId: ({envelope.EnvelopeId}) and status: ({envelope.Status})");
await publishEndpoint.Publish(new DocumentSentForSigning(context.Message.Id, envelope.EnvelopeId));
logger.LogInformation($"Published a DocumentSentForSigning event for a document with id ({context.Message.Id})");
- In the final step, we periodically query the API for status changes concerning a specific bundle of documents. We do this in bulk to limit the number of API requests and minimize the size of the transmitted data. If any of the documents have been signed, we download them, update their status in the database, and send them for further processing within our system. To implement the periodic queries, we used an open-source library called Quartz. This library enables easy implementation of such a mechanism while also offering a variety of useful features.
DocuSign has several interesting features that can be very useful when building a custom document generation solution. Let’s take a look.
DocuSign features: automatic detection of signature placement
DocuSign offers several approaches for placing signatures on electronic documents. One such approach is manual insertion of the signature by the user at the appropriate location. However, this may not be the most efficient solution when dealing with documents that require multiple signatures. In such cases, it is best to use the Auto-place functionality. This feature ensures that the signature box is automatically inserted at locations where the API encounters a specified keyword. In the earlier example, we used the word “Signature,” and a signature box appeared at each occurrence of the keyword (see Figure 1 below).
Fig. 1 A signature box placed where a document needs to be signed
After signing the document, it changes in the way shown the Figure 2:
Fig. 2 An electronically signed document
Visible words on the document as AnchorString are not the best solution. A good practice is to replace such words with tags like \s1, which appear on the document in the background color and are invisible to users. In this way, the API knows where to place the signature box, there’s no risk that such a word will appear in the actual text of the document, and we have flexibility in choosing the location.
DocuSign features: batch document querying
The best practice for responding to a document signing event is to set an appropriate address that is invoked in response to such an event. However, for security reasons, we may not always be able to specify such an address as it requires exposing a part of the system to Internet access. In cases with large volumes of data, it would also be a bad solution to query the API for the status of each document individually. This would result in a high load on the API, leading to additional costs or even reaching the limit of the number of queries (documentation indicates that status queries are not recommended more often than once every 4–6 hours).
In this case, DocuSign recommends using the listStatusChanges method and querying the API at regular intervals, such as every hour, for a batch of documents that have changed their status recently. We applied this solution in this case, i.e., at specific intervals, we check if the documents marked in our local database as sent have already been signed.
DocuSign features: signing via SMS
The eSignature API also allows for document signing via SMS. To implement this functionality, simply modify the part in the above example where we define the envelope, specifically the person responsible for signing the document, in the following way:
Signer signers = new Signer
{
Name = signerName,
RecipientId = "1",
RoutingOrder = "1",
PhoneNumber = new RecipientPhoneNumber
{
CountryCode = signerCountryCode,
Number = signerPhoneNumber
},
};
In such a case, a notification about the document to be signed will be sent to the user at the specified phone number, and they will be able to sign it, for example, using a mobile application.
DocuSign electronic signature API integration—a wrap-up
The presented microservice was one of the more interesting ones among all those implemented in the project, as it provided an opportunity to use an external API and explore its functionality.
DocuSign offers extensive possibilities when it comes to signing documents, but using the eSignature API is not very difficult. The official documentation is very detailed and contains a variety of examples on which to base your solutions. It is also worth paying attention to the best practices indicated by DocuSign, as they often contain valuable tips on how to use the API’s features.
