Signing enables efficient and paperless document and signature flows. The cloud service is designed to ensure the legal validity of processes, with the ability to use all types of electronic signatures, time stamps, and regulatory storage.

API integration ensures full adaptation within pre-existing management setups.

In association with Onboarding, Signing enables the management of the entire identification and contextual signature release flow, so that documents and contracts can be signed immediately.

Signing provides three different experiences, relating to:

• ADMIN, in charge of creating, editing and disabling users (admins, instructors and signers) and robots, as well as creating and signing practices

• INSTRUCTOR, in charge of creating and editing Signer, as well as creating and signing practices

• SIGNER, in charge of signing practices.

The platform allows you to choose the desired signature profile described in table:

The main signature types are described in table:

There are different environments for Signing API integration.

They are divided according to the purpose for which the service can be implemented.

The same environments can be used for access to the platform via browser.

Before you begin

1. Choose the right environment to contact among SANDBOX, DEMO, LIVE (e.g. https://web.sandbox.signingtoday.com)

2. Choose the authentication method between the following options:

   • Authentication via Bearer, by setting a bearer token in the header of an HTTP Request

   • Oauth2.0, by calling the API /oauth passing the user credentials

3. Remember that, if the request has a body, another HTTP header is required: Content-Type, with application/json value.

4. (optional) If you are using a Robot user, choose a webhook service to receive notifications from Signing. The Signing platform sends POST requests which contains some useful data, for example:

   • DST identifier: data.dst.id;

   • Status of the DST: data.status;

Step 1 Create a DST

Create a DST using the Create a DST API, necessarily defining:

1. At least one documents[n].document_uri that's the document URI to sign

2. At least one documents[n].groups[n][n].signer object with first_name, last_name and email that are data of the expected signer

Note: In the Create a DST API there are some examples of which include electronic signature with click, electronic signature with OTP, graphometric, advanced, qualified signature.

Step 2 Get the signature ticket

The signature_ticket is a pre-authenticated link useful to access to the document to sign. This link is sent to the user's e-mail address set in documents[n].groups[n][n].signer.email.

Otherwise, you can inhibit the email sending and extract the signature ticket to provide to the user. In the Create a DST API, you can disable the email sending asserting the boolean parameter metadata.studio_email_disabled ; then, you can call the Retrieve a DST API passing the request identifier and get the documents[n].groups[n][n].signature_ticket value.

Step 3 Sign the DST

So, you can open the link received in the email or redirect the user to the URL exposed by the documents[n].groups[n][n].signature_ticket parameter.

According to the signing mode, follow the on-screen instructions to sign the document.

Step 4 Download signed documents

You can obtain signed documents of a specific DST by calling the Retrieve DST API declaring in URL path your slug and the DST id.

Explore the documents[n].document path which is valued by the URL of the signed document.

Then, make a call to the obtained URL by authenticating adding the field "Authorization: Token {{token}}" to the HTTP request header. Exploring every document value in documents[n] array you can easily download all signed document.

To test the workflow, complete yourself the process and check what happen at the end.
Below is a graphic that allows you to see a simple integration scenario.

APIs use the right HTTP verb in every situation.

A DST may have different states depending on the operations performed as described below.

To use the Bearer authentication method, an administrator of the Signing organization must create a robot user to retrieve the associated Bearer token. The robot configuration is available on the GUI of the Signing web application.

For this purpose, it is necessary to log in to the web application entering the following credentials: organization, username and password.

Once you have logged in, to create the Robot User you need to go to the Users section of the menu, clicking on the icon on the top left represented by the 3 horizontal rows in a stack.

At this point, you must click on the Add User button in the top left-hand corner, select the Robot entry in the first select box Account Type. Then choose a username and an application name and finally click on the Create button.

Click on the newly created user in the list to access the Robot User summary page and select, on the upper left, the menu highlighted by the three vertical dots to the right of the Contact Data field.

Select Manage Token to set the Authentication Token, i.e. the Lifetime Token to be used in API calls.

From the modal that appears, it is possible to configure the URL of the webhook to be associated with the Robot User, as well as the header and authentication settings.

Those settings will be used to access the documents[n].document_uri parameter and the webhook URL relatively to the DSTs created by the Robot User you are setting up. However, the documents[n].document_uri authentication settings can be overridden by the documents[n].document_uri_options described in the Digital Signature Transactions (DST) paragraph.

The Webhooks field of the Robot configuration represents the URL associated to the server able to listen for notifications, which will be sent by Signing as POST requests, with JSON-type payload, about DST and signature status.

After configuring the Robot user by entering the webhook address, we can proceed to analyze the notifications that will be received as a result of the creation of a DST and the signing of a DST.

Every state described in this paragraph follows the finite-state machine below.

Creation of a DST

After performing the call to the Create a DST API, notifications are received for two different processes:

• Saving the created DST

• Creation of the signature request

Upon saving the DST, the system sends us the notification with Http Header user-agent valued as Apache-HttpClient. This notification informs you that the DST is created and is available the dst id following the data.dst path and the status following the path data.status.

  {
    "message": "DST_STATUS_CHANGED",
    "meta": {},
    "data": {
      "status": "pending",
      "title": "<title>",
      "dst": "<dst-id>",
      "reason": null,
      "slug": "<slug>",
      "metadata": {}
    },
    "created": "<date>"
  }

Simultaneously, the system alerts us to the creation of the signature transaction by sending a single notification structured as follows where we can read general information about that transaction such as:

• who the signer is following the path data.signer valorized with the user's e-mail

• the id of the signature transaction following the path data.dst.id

• the organization it belongs to following the path data.slug

• the signature profile following the path data.profile

  {
    "message": "SIGNATURE_STATUS_CHANGED"
    "meta": {},
    "data": {
      "profile": "<profile>",
      "status": "pending",
      "group": 0,
      "dst": {
        "title": "<title>",
        "id": "<dst-id>",
        "metadata": {}
      },
      "page": "<page_number>",
      "signature": "<signature-id>",
      "signer": "x-mail.mail.com",
      "position": "rect: 216, 117, 216, 101",
      "document": {
        "order": 0,
        "display_name": "<doc-name>",
        "id": "<doc-id>",
        "metadata": {}
      },
      "automatic": false,
      "slug": "<slug>",
      "metadata": {}
    },
    "created": "<date>"
  }

Signing of a DST

Upon signing you receive two notifications the first one notifying you that the signature transaction has completed by receiving the json where you can see that the status changes to performed.

  {
    "message": "SIGNATURE_STATUS_CHANGED",
    "meta": {},
    "data": {
      "profile": "<profile>",
      "status": "performed",
      "group": 0,
      "dst": {
        "title": "<title>",
        "id": "<dst-id>",
        "metadata": {}
        },
      },
      "page": "<page_number>",
      "signature": "<signature-id>",
      "signer": "x-mail.mail.com",
      "position": "rect: 216, 117, 216, 101",
      "document": {
        "order": 0,
        "display_name": "<doc-name>",
        "id": "<doc-id>",
        "metadata": {}
      },
      "automatic": false,
      "slug": "<slug>",
      "metadata": {}
    },
    "created": "<date>"
  }

The second one notifying you that dst is closed, and you can see that the status is changed in performed.

  {
    "message": "DST_STATUS_CHANGED",
    "meta": {},
    "data": {
      "status": "performed",
      "title": "<title>",
      "dst": "<dst-id>",
      "reason": null,
      "slug": "<slug>",
      "metadata": {}
    },
    "created": "<date>"
  }

Reject a DST

It is possible that a DST may be rejected by the signer during the signing process, in this case the system will send a single notification informing that the DST has passed into cancelled status.

  {
    "message": "DST_STATUS_CHANGED",
    "meta": {},
    "data": {
        "status": "cancelled",
        "title": "<title>",
        "dst": "<dst-id>",
      "reason": "declined",
      "slug": "<slug>",
        "metadata": {}
      },
      "created": "<date>"
  }

It is possible to set up a case with multiple signatories sorted into signature groups. Signatories from the same group may sign in any order.

When all the signatories of a group have affixed their signature, the possibility of signing for the signatories of the subsequent groups is unlocked (and only then will the signature requests be sent via email, if the sending of the emails has not been inhibited).

In the Create a DST API, the documents[n].groups parameter is a nested ordered list: documents[n].groups[n] is the list of the groups and the documents[n].groups[n][n] second-level list is the list of signers

The signature_ticket is a pre-authenticated URL to be exposed to the user. Through this link, the user can access the graphical user interface to perform the service.

The signature ticket is generated after the creation of the dst. It can be retrieved in the data.documents[n].groups[n].signature_ticket field in the response to the API Retrieve DST.

The Signing platform sends automatic signing requests to the user via e-mail. It is also possible to inhibit the email sending. In this case you have to set metadata.studio_email_disabled field, in payload of Create a DST request, to true for disabling the automatic sending of notification e-mails.

The API section having tag Robots allows to:

• Authenticate like robot user

• Get the robot configuration

• Edit the robot configuration

To perform this api you need to have an ADMIN account.

The api section having tag Authentication allows to:

• Perform login, simply using Oauth2.0 protocol

The api section having tag Users allows to:

• Create a user

• Modify user's configuration

• Delete a user

• Enable or disable a user

• Retrieve information about a user

To perform this api you need to have an ADMIN account.

The API section having tag Manage password allows to:

• Change passowrd for a specific user

• Send email for password changing

The API section having tag Digital Signature Transaction allows to:

• Create a DST

• Retrieve a DST

• Retrieve all DSTs

In creating a DST there is a documents[n] field that presents a list of documents. Each document is represented by the documen[n].document_uri or documen[n].document field.

In documen[n].document_uri is possible to pass a URL to access the document to sign. Otherwise documen[n].document field is possible to insert a PDF as base64.

If you use the document URI, you can configure the documents[n].document_uri_options field passing headers, body and method this is an additional override level for the http options, defined in Robot User configuration, for downloading documents.

The following configurations are possible:

• Basic Authentication:

  • auth_username(string): username for http authentication

  • auth_password(string): password for http authentication

  • auth_mode(string): authentication mode -basic(default),digest

• Client Authentication:

  • client_cert(string): base64 of public key pem

  • client_key(string): base64 of the private key pem

• HTTP Authentication:

  • headers(json): list of additional headers for requests

Also you can change the method of the document download request or add a body.

It's even possible to set the placeholder location of a visible signature appearance, with the following parameters:

• documents[n].groups[n][n].where.page with the integer indicating the page

• documents[n].groups[n][n].where.position with a string such as 'rect: 10mm, 50mm, 110mm, 80mm' Note: For performance reasons related to the call of Create a DST, it is preferable to pass the document as a URL rather than loading the entire file in Base64 format.

Signature Label

It is possible to set signature label position, size, image and text. In particular, the position key accepts as its value the definition of a rectangle as follows: "position": "rect: 10mm, 50mm, 110mm, 80mm".

The above exaple is defining a graphic signature of size 10cm*3cm placed 5cm from the bottom margin and 1cm from the left margin. The generic structure of the rectangle definition is as follows: rect: x1, y1, x2, y2 with origin in the bottom left-hand corner. Various units are supported: millimeters (mm), inches (in) and points (pt). By default, if units of measurement are not specified, points are used.

The dots are calculated on a document dpi of 72 so 10mm equals ((10*72)/25.4)pt. To make a signature invisible, only the page must be defined in the documents[n].groups[n][n].where field of the signature.

If your DST list is not automatically updated, due to a weak connection or other problems, you can simply reload the page and get the updated list.

To obtain the robot user's token you have to access to Signing, then click on the burger menu and select Utenti.

Then select the target robot user and click on it, now click on the three points menu as shown in figure.

Click on manage token and copy the token.

The client id is retractable in the email sent by Bit4Id to your organization, the secret must be requested.

For disabling a user access to Signing, then click on the burger menu and select Utenti.

Then select the target user you want to disable and click on it, now click on the three points menu as shown in figure.

Now click on Disabilita.

If you want to disable a user via API you can use the Enable or disable user API described in user section.

After successfully creating the DST you have to call Retrieve DST API and retrieve the signature ticket by taking the value from the field data.documents[n]. groups[n]. signature_ticket into response.

In this case you need to set the field metadata.studio_email_disabled, in the payload of the DST creation request, to true to disable the automatic sending of notification emails.

For changing webhook in robot user configuration you have to access to Signing, then click on the burger menu and select Utenti.

Then select the target user you want to disable and click on it, now click on the three points menu as shown in figure

Click on manage token and edit the webhook field with the new url.

For downloading signed document you have to choose the target DST in status performed then call the Retrieve a DST API declaring in URL path your slug and the DST implemented.

Then, you can explore the documents[n].document path which is valued by the URL of the signed document.

Then, make a call to the obtained URL by authenticating adding the field Authorization: Token {{token}} to the HTTP request header. Exploring every document value in documents[n] array you can easily download all signed document.

In Subscrivia you can set a urlback at the creation stage.

The urlback parameter must be added following the path documents[n].groups[n].urlback in the payload of the Create a DST API.

The link of the urlback will be used to redirect the end user after they have successfully completed the signing operation.