Sign a document with form fields

Overview

Some business workflows generate documents that must be filled out by the Signer before they sign the document. This example will illustrate how developers can upload a document containing form fields, populate values of the fields and add additional fields using the SigningHub REST API.

Sample code

Download the Postman sample code.

Download the accompanying sample code documentation.

Prerequisites

In order to populate fields on a document, the developer must know what the name of the fields are.

The document must be a valid standard ISO PDF document.

Use Case

This type of workflow can be used for example by a hotel or a resort that let new guests sign an indemnity form on arrival.

A third-party application generates the document and send it to SigningHub. Fields with known values can be populated and the fields with unknown values can be left for the Signer to fill out.

A date field can be added to the document that will be auto populated at the time of signing.

Process flow

Adding fields process.

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

  1. Prepare the workflow.

  2. Populate the fields on the document.

  3. Draw any additional fields.

  4. Share the document.

  5. SigningHub sends email notification to Signer.

    1. Signer log into SigningHub.

    2. Signer fill out required fields

    3. Signer sign the document.

  6. Third-party application check the document status.

  7. Third-party application download the signed document.

  8. Third-party downloads the forensic Workflow Evidence report.

  9. Deletes the document.

Requests

Add fields requests.

The following requests must be called to share a document with one 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 electronically 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 in the following steps. For the first signer, set the value to 1.

 

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.

 

Unless specified, the user will not be prompted to enter a password or an OTP to view the document.

 

See the sample code Password protect access to a document or OTP protect access to a document for an example on how to protect access to a document.

 

 

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.

 

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.

 

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

 

Field_type must be set to "ELECTRONIC_SIGNATURE".

 

 

Step 6 – Update form field

Overview

Set the value of a form field on the document.

 

Online Documentation

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

 

Description

This requests updates a text field in the document with the value specified in the request.

 

Parameters

The access_token is obtained during Step 1 - Authenticate.

 

The package_id is obtained during Step 2 – Create Package.

 

The document_id is obtained during Step 3 – Upload document.

 

Field_name: this parameter specifies the name of the text field to update.

 

Page_no: specifies on which page to find the text field.

 

Placeholder: The text will appear in the text field while view the document. For this example it can be left empty.

 

Value: This is the actual value that will be placed in the text field.

 

 

Step 7 – Add date field

Overview

Add a date field to the document.

 

Online Documentation

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

 

Description

This request will place a date field on the document at a specified location.

 

The date field will automatically be populated by SigningHub at the time of signing.

 

Parameters

The access_token is obtained during Step 1 - Authenticate.

 

The package_id is obtained during Step 2 – Create Package.

 

The document_id is obtained during Step 3 – Upload document.

 

This request will look for the text specified in the field search_text in the document and place the date field at that location.

 

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

The size of the date field can be controlled with the dimension field.

 

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

 

Field_type must be set to "DATE".

 

 

Step 8 – 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

 

 

Step 8.1 – Signer fill out form fields

Overview

The signer logs into SigningHub and manually fills out any open text fields.

 

This is a manual step performed by the user and as such there is no requests to call.

 

Online Documentation

https://manuals.ascertia.com/SigningHubv7/default.aspx#pageid=1164.

 

Description

The Signer manually enters data into any empty text fields on the document before signing.

 

Parameters

N/A

 

 

Step 8.2 – Signer sign the form

Overview

The signer logs into SigningHub and manually signs the document.

 

This is a manual step performed by the user and as such there is no requests to call.

 

To programmatically sign a document, see the sample: One Signer workflow.

 

Online Documentation

https://manuals.ascertia.com/SigningHubv7/default.aspx#pageid=1164.

 

Description

The Signer manually signs the document.

 

Parameters

N/A

 

 

Step 9 – Get document status (Optional)

Overview

Get the workflow status.

 

Online Documentation

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

 

Description

The document status request retrieves the document’s current status.

 

Developers can use this request to periodically retrieve a document’s status.

 

The document status will be ‘Pending’ until all the Signers have electronically signed the document. After calling the document’s status will be ‘Completed’.

 

Parameters

N/A

 

 

Step 10 – Download document

Overview

Download the digitally signed document.

 

Online Documentation

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

 

Description

The digitally signed document is downloaded as a base64 string.

 

To download the signed document in a binary format, see this API request.

 

Parameters

Provide the package_id of the signed document to download.

 

 

Step 11 – Download Workflow Evidence report (Optional)

Overview

Download the forensic Workflow Evidence Report document.

 

Online Documentation

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

 

Description

A forensic report (Workflow Evidence report) can be downloaded optionally.

 

The forensic report contains an audit trail of all the actions that happened during the signing workflow.

 

The forensic report has been digitally signed to proof that the audit trail has not been tampered should a dispute arise later on.

 

Parameters

Provide the package_id of the forensic report to download.

 

 

Step 12 – Delete document

Overview

Delete the specified document (and containing package).

 

Online Documentation

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

 

Description

Finally, the package and signed document is deleted of SigningHub to free space on the SigningHub Enterprise.

 

Parameters

Provide the package_id of the signed document to delete.