OTP protect access to a document

Overview

This sample is similar to the Password protect access to a document workflow, except, in this sample the Signer will be requested to open the document with a One-Time-Pin (OTP) sent to their mobile phones.

Sample code

Prerequisites

For electronic signatures there are no prerequisites for the Signer to register on SigningHub.

The Signer’s mobile phone number must be known.

Use Case

SigningHub allows developers to protect access to documents with a password. The Signer will be prompted to enter the password to view the document. The password must however be shared securely with the Signer. If a secure sharing mechanism is not available, a One-Time-Pin can be used to protect access to the document.

Process flow

OTP protect a document process.

At a high level, the sample code will perform the following steps:

  1. Prepare the workflow.

    1. Configure OTP protection.

  2. Share the document.

  3. SigningHub sends email notification to Signer.

  4. SigningHub prompts the Signer to enter an OTP that was sent to his / her mobile phone.

  5. If the OTP is correct, SigningHub will display the document to the Signer who then has the opportunity to electronically sign the document.

Requests

OTP protect a document  requests.

The following requests must be called to protect document access with an OTP and then share the document with the Signer.

Step 1 – Authenticate

Overview

Authenticate to SigningHub.

 

Online Documentation

https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1010.

 

Description

Authenticate to SigningHub, to start transacting with SigningHub.

The required authentication parameters will be supplied by LAWtrust.

Contact LAWtrust to get access to the testing environment.

 

Parameters

The scope parameter tells the system who the Document Owner is. Use the email address of the Document Owner to identify the owner.

If this parameter is not set, the integration account used to authenticate to SigningHub will be considered to be the Document Owner.

 

Take note of the access_token returned by the server. The access_token will be needed in subsequent requests.

 

 

Step 2 – Add Package

Overview

Create a package to upload documents to.

 

Online Documentation

https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1020.

 

Description

The first step to creating a workflow on SigningHub is to create a package. This step tells the system what the name of the package is that you want to create.

 

A package can contain one or more documents.

 

Parameters

The access_token is obtained during Step 1 - Authenticate.

 

Take note of the package_id returned by the server. The package_id will be needed in the subsequent requests.

 

 

Step 3 – Upload document

Overview

Upload a document to the package created in the previous step.

 

Online Documentation

https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1022.

 

Description

Upload the document that must be digitally signed to the system.

 

Parameters

The access_token is obtained during Step 1 - Authenticate.

 

The document_id returned by the server will be needed in requests pertaining to the uploaded document.

 

 

Step 4 – Add Signer 1 to the workflow

Overview

Add a signer to the workflow.

 

Online Documentation

https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1047.

 

Description

Add the name and email address of the person that must sign the document.

 

Parameters

The access_token is obtained during Step 1 - Authenticate.

 

The package_id is obtained during Step 2 – Create Package.

 

Signing_order specifies the Signer’s order to sign. The order number will be required

 

Set the field email_notification to true. If the parameter value is true, SigningHub will send an email with a link to the document to the Signer. If the signer clicks on the document, the document will be opened in SigningHub and displayed to the user.

 

 

Step 5 – Insert signature block 1

Overview

Draw a signature block for signer 1 on the document.

 

Online Documentation

https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1182.

 

Description

Add the name and email address of the first person that must sign the document.

 

Parameters

This request will draw a signature block on the document where the first signer’s signature must be placed.

 

This request will look for the text specified in the field search_text in the document and place the signature block on the document.

 

Order corresponds to the Signer’s order in which he / she must sign.

 

The field placement can be used to position the signature block relative to the search_text.

The size of the signature block can be controlled with the dimension field.

 

Field_type must be set to "ELECTRONIC_SIGNATURE".

 

 

Step 6 – OTP protect the document

Overview

Configure an OTP to protect access to the document.

 

Online Documentation

https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1058.

 

Description

Configure an OTP to protect access to the document. The Signer will have to enter the OTP that was sent to his / her mobile phone to be able to view the document in SigningHub.

 

Parameters

The access_token is obtained during Step 1 - Authenticate.

 

The package_id is obtained during Step 2 – Create Package.

 

The order must correlate to the Signer’s signing order.

 

Apply_to_all: Set this value to false.

 

Authentication -> enabled must be set to true for the password to be applied.

 

Authentication -> password -> enabled must be set to false.

 

Authentication -> password -> user_password: Leave this value empty.

 

Authentication -> sms_otp -> enabled: must be set to true.

 

Authentication -> sms_otp -> mobile_number: The number of the mobile phone the OTP must be sent to. Please note: the phone number must be in international format. For example, “00445566778899

 

The values for the other enabled parameters can be set to false.

 

 

Step 7 – Share document

Overview

Share document.

 

Online Documentation

https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1025.

 

Description

This request notifies SigningHub that the workflow configuration is complete and the signing workflow can start.

 

Parameters

N/A

 

 

After calling the Share request SigningHub will send an email to the Signer with a link to the document to be signed.

The Signer will be prompted for the OTP configured in Step 6 before they can view the document.

OTP protects access to document.

Document access protected with OTP