Overview

The Sign API is a RESTful web service that allows businesses to obtain electronic signatures from their customers. Documents signed using the Sign API are legally binding and can be delivered to the involved parties quickly and efficiently, ensuring greater levels of transparency and traceability as well as lower abandonment rates.

The Sign API serves as Signicat’s single integration point for electronic signatures and all underlying methods, both in a browser and in the context of a native app. It also allows merchants to archive the documents after they have been signed.

Introduction

Key concepts

Document

A resource of the Sign API.

A document is any file which is uploaded to the Sign API to be signed.

End-user

The person who has to sign the documents.

Service provider

Also called “merchant”. The entity that will integrate with the Sign API.

Signing order

A resource of the Sign API.

A signing order is an action that is initiated by a merchant to obtain the signature of one or more subjects on one or more documents.

Main differences between the DocumentService API and the Sign API

The main technological difference is that, while the DocumentService API is a SOAP API, the Sign API is a REST API. Additionally, the Sign API is a one-stop shop compared to the SOAP services, which require the support of several subsystems.

The main functional differences between the two APIs are as follows:

 

Getting started

Please refer to the documentation on Accessing Signicat REST Services.

Reference documentation

For detailed reference documentation on the API and test examples please refer to the Sign API Swagger Documentation page.

Using the API

The Sign API is used to obtain electronic signatures on digital documents from end-users or businesses. A basic process can be summed up as follows:

  1. The service provider uploads the document in PDF format.
  2. The service provider creates a signing order.
  3. The signer receives a notification stating that the signing order is ready. The URL attached to the notification redirects the end-user to the task.
  4. The end-user signs the document using one of the available identity methods.
  5. The signing result is created.

The sub-sections below contain more detailed information about the actions that must be carried out by the merchant throughout the process.

STEP 1: INITIAL SETUP

Obtain an access token and use it to upload a document to Session Data Storage (SDS) for temporary storage. To do so, make a POST call to the /documents endpoint. The document will remain on the server for 30 minutes, after which it will be deleted unless it has been used in a subsequent web service request.

STEP 2: CREATE AND SEND THE SIGNING ORDER

Create the signing order using the Create signing order endpoint. The signing order can contain more than one task: each Task item should contain the information relevant for each of the tasks that must be carried out by the end-user. A task may involve signing one or more documents (SIGN), opening a document (VIEW), or uploading a document (UPLOAD). They will sometimes require the end-user to log in.

The merchant can obtain three different types of signature depending on their use case: an authentication-based signature, a signed statement, or a third-party signature. Optionally, it is possible to archive the document electronically once it has been signed by the end-user: this is configured by setting sendResultToArchive to true.

The language for the interface can be defined in the language field. The following languages are available (the codes in brackets are the codes you must use in the sign order request):

Bear in mind that this only applies to the Sign solution and that the identity methods used to obtain the end-user’s signature may support different languages, often a subset of the ones listed above.

The end-user can be notified automatically that the document is ready to be signed after the signing order has been created. In the Notification data type, the merchant can configure notifications to be sent to the end-user or to a system. Notifications can be sent as an SMS, an email, or a URL. Bear in mind that, in order for a URL notification to work, you must notify Signicat beforehand.

Request example

{
  "tasks": [
    {
      "id": "1",
      "documents": [
        {
          "id": "doc-1",
          "description": "Document",
          "action": "SIGN",
          "source": "SESSION",
          "documentRef": "200320193lrce4j85hpgdns4ivbuts5dy7pgarm1e0iozjq4qh2tey77jv",
          "sendResultToArchive": true
        }
      ],
      "signatures": [
        {
          "methods": [
            {
              "name": "nemid",
              "type": "AUTHENTICATION_BASED"
            },
            {
              "name": "nbid",
              "type": "AUTHENTICATION_BASED"
            },
            {
              "name": "sbid",
              "type": "AUTHENTICATION_BASED"
            }
          ]
        }
      ],
      "language": "en",
      "notifications": [
        {
          "id": "not-1",
          "recipient": "ginny@signicat.com",
          "sender": "noreply@signicat.com",
          "header": "Documents ready to be signed ",
          "message": "Please sign this document: ${{taskUrl}}",
          "type": "EMAIL",
          "schedule": [
            {
              "triggerStatus": "CREATED"
            }
          ]
        }
      ]
    }
  ]
}
STEP 3: GET THE RESULT AND DOWNLOAD THE SIGNED DOCUMENT

In order to get updates about the status of the signing order, the merchant can use the Get status endpoint. The response will contain information about the status of the task, which can be created, completed, rejected, expired, or deleted. It also contains status information for each of the documents in the task. When the status is “completed” it means that the end-user has signed the document and the process is finalized.

If the merchant specified that they wanted to send the signed document to permanent storage in step 2 (sendResultToArchive field), they will be able to download the signed document from the archive for later use and validation. This can be done through the Get archived document endpoint.

It is also possible to download the signed document if it has not been archived. In this case, the number of days before the signing order and all associated documents (both original and signed) will be deleted is configured as a combination of the following: