Photo from Unsplash

Technical electronic signature implementation

Electronic signature has been omnipresent, and many services are using it more and more. Last year, at Source we have implemented this feature for some of our clients. In this article, we will share with you how we approached it. With this goal in mind, first, we will see the theory, and then, the technical aspect.

Understand the electronic signature protocols

Seeing as the subject requires strong legal expertise, we will try to make it as accessible as I can, and we are only going to tackle the fundamentals.

What is an electronic signature?

An electronic signature (or e-signature) is a legal way to get consent or approval of electronic documents. It can replace a handwritten signature in any process. Security is frequently split into three levels: simple, advanced, and qualified.

Simple

The simple electronic signature has a low level of security. With that, we don’t have any real evidence as to who the signer really was. We don’t have the mandatory technical feature, but it is recommended to have a phone number validator. It works for simple contracts: insurance, opening bank account, employment contract, lease contract, etc.

Advanced

This type of electronic signature has legal validity (example regulate in EU by eIDAS; ETSI) with a much higher level of security. It must validate the identity of the signer. For this reason, our technical implementation will need to validate both the identity and the phone number. This level of security is mandatory for complex contracts: sales agreements, credit contracts, life insurance, etc.

Qualified

The qualified electronic signature offers a better level of security, it is the strictest and most complex of the three. Moreover, it is considered, all across the EU, as the legal equivalent of a handwritten signature. It uses the same criteria of the advanced electronic signature, plus an in-real-life identity validation. The user will be provided with a hardware device (such as a USB key, with a token on it) in order to validate their identity during the signing process. As this process can get pretty complex, I highly recommend reaching out to signing services (YouSign, SignEasy, DocuSign, and so on) in order to get more information.

Note, before diving into the technical implementation, please check the security level you need according to your documents, as the implementation and pricing might differ.

Now, we have seen the theory, let’s move on to the technical implementation!

Technical approach

You will find many services providing electronic signing, with different prices, contract authorization, and more. But, in the online documentation of service you will often find this signature workflow:

E-signature workflow

At Source, we used two services YouSign & SignEasy, in two different projects. I will try to explain the reasons why we choose one or the other.

First, we used YouSign because we simply needed a signing process for contracts, matching EU legal requirements. In summary, the pros are:

• Contracts authorization EU only
• Good customer service

Second, we also used SignEasy, mainly because we needed contracts with worldwide authorization. Here are some of the main advantages:

• Contracts authorization Worldwide
• Custom document Template is well-thought-out
• Price: with a trial plan, then starting at 8$/month

Both solutions share the same pros: good documentation, and easy implementation (API quality, different examples). Then, in the next part, I will explain how to implement standard e-signature, using YouSign (the process is quite the same if you choose to go with SignEasy).

Basic implementation with YouSign

Now, we will see how to implement a simple solution, using YouSign. If you want to learn more, I recommend looking at the very well-built documentation. The goal of this part is not to provide a deliverable at the end of the step, but more to explain to you the different steps of the electronic signature flow including a third-party service. Best practices can differ according to the API provider you choose, but in our case, we will do a basic implementation, using YouSign.

Upload file

POST {{API_URL}}/files
First, we need to upload the file, we would like our users to sign.
The content must be converted in base64 without the header in the body.
(remove header: data:application/pdf;base64)

Parameters: POST /files

After sending the request, you will receive a complete response containing different properties. In order to create a procedure, we need to use the id.
(example: /files/e0e228fe-1824–40ac-827f-c7ea3cd63c25)

Create procedure

POST {{API_URL}}/procedures
This step allows you to link, the previously added document and the information of the signer.

Parameters: POST /procedures

To create the procedure, we need to make a POST request, using the payload just above.

• a “start” boolean set to true
• a “fileObjects”, with the file’s id in it
• potential extra mentions
• position of the signature (in my example, on page 1, positioned at “57,50,155,100”)

More parameters are available and can be found in the documentation.

So, we just linked the file and the signatory to the same procedure.
Now, the signatory can sign the document.

Note, if you don’t want to follow the next steps you can add a preview embedded (instruction in the documentation “Embedded integration”).

Sign document with SMS

Now, we are on the signatory side and we want them to validate (sign) our document. This is a mandatory step that needs to be done using a mobile phone. So, we need to send an SMS, with the following request, from which you will need to save the authentication id (from the response):

Note, for the next query, you need to get the member id, with this request {{API_URL}}/procedures/{{PROCEDURE_ID}} (don’t need parameters).

POST {{API_URL}}/operations

Parameters: POST /operations

Then, you will receive an SMS with a code with which the signatory can validate the document, with the following endpoint (using authentication id from operations request’s response):

PUT {{API_URL}}/authentications/sms/{{AUTHENTIFICATION_ID}}

Parameters: PUT /authentications/sms/{{AUTHENTIFICATION_ID}}

Perfect, you have signed the document with our custom preview. It is possible to download it (to check if the document has been signed), with this endpoint: {{API_URL}}/files/{{FILE_ID}}/download

During all steps, you can get with {{API_URL}}/procedures/{{PROCEDURE_ID}}, if the procedure status is updated, its different values ​​can be:

• draft: The signing process has not started, so no one can sign it. But it is possible to edit the procedure.
• active: Members can sign the document.
• finished: All members have finished sign the document.
• expired: You can set an expiration date in the expiresAt field. After this date, members can't sign it anymore.
• refused: At least, one of the members decided to refuse the procedure.

This is the end of a basic integration! You have all steps to initialize your first electronic signature workflow, using YouSign.

Thanks

Voilà, to summarize before going into the code, please determine your level of electronic signature and whether the provider’s API meets the need for your context of use.

I hope this article will help you to understand better the implementation of this feature in your application, thanks for reading.