SigningHub tight integration sample

Overview

Third-party integrators can create a seamless signing experience by embedding SigningHub’s functionality inside their own applications.

Sample code

Use Case

An application, like a bespoke Customer Relationship Management application, that allows employees, vendors or new clients to log into the platform to digitally sign their contracts, invoices, purchase orders is a good use case for tight integration.

The Signers will use the system in an environment that they are already familiar and comfortable with.

Process flow

Tight integration process flow.

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

  1. Prepare the workflow.

  2. Share the document.

  3. Signer 1 logs into the third-party application.

  4. The document is displayed to the Signer using the SigningHub iFrame.

  5. Signers signs the document.

  6. The third-party checks the status of the document.

  7. If the document status is “Complete”, the signed document is downloaded.

  8. The Workflow evidence report is downloaded.

  9. The signed document is deleted from SigningHub.

Requests

Tight integration requests.

The following requests must be called to share a document with one Signer. The third-party authenticates to SigningHub and creates a workflow.

The document to be signed is displayed to the Signer using the SigningHub iFrame.

The Signer signs the document and the signed document is retrieved by the third-party application.

Optionally the Workflow evidence report can be downloaded.

During the final step, the signed document is removed from SigningHub.

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 parameters will be supplied by LAWtrust.

Contact LAWtrust sales 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 pack 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 in the following steps. For the first signer, set the value to 1.

 

Set the field email_notification to false. Prevent SigningHub from sending a notification email to the user that they have a document to digitally sign.

 

 

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.

 

Take note of the field field_name returned from the server. The field name will be needed for Step 8 – Sign Signer 1.

 

 

Step 6 – 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 7 – Generate link

Overview

Generate a link to the document that must be signed.

 

Online Documentation

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

 

(See Step 12 - Generate Integration URL for Encrypted Data (Coding) at the bottom of the page)

 

Description

This step generates a link that will used during Step 8 to display the document to the Signer.

 

Parameters

The access_token will be required during the next step Step 1 - Authenticate.

 

Package_id: The package ID of the document the Signer must sign.

 

user_email: the user that must sign the document’s email address. Specified during Step 4 – Add Signer to the workflow.


callback_url: Specifiy a URL for the Signer to be redirected after signing the document.


collapse_panels: If set to true, SigningHub will automatically collapse the panels around the document when the user opens the document for viewing.

 

The URL returned by the request will be need during Step 8 – Display the document with iFrame.

 

 

Step 8 – Display the document with iFrame

Overview

Display document to the Signer

Online Documentation

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

 

Description

Using the link generated during Step 7 – Generate link, the document is displayed to the Signer.

 

If electronic signatures are used, the Signer will not be required to log into SigningHub to view the document.

 

However, if the signature type is digital, the Signer will first be prompted to log into SigningHub before they are able to sign the document.

 

Parameters

Place the link in an iFrame:

<iframe id="id_sh_iframe" src="{link}" name="sh_iframe" width="100%" height="100%"/>

 

Link is generated during Step 7 Generate Link.

 

 

Step 8.1 – Signer signs document

Overview

For this step no request is sent to SigningHub via the API. 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=1156.

 

Description

The Signer manually signs the document.

 

After the Signer clicks the Close or Finish button, SigningHub will redirect to the URL configured during Step 7 Generate_Link in the callback_url field.

 

Parameters

N/A

 

 

Step 9 – Get document status

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 digitally 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 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 signed document is deleted of SigningHub to free space on the SigningHub Enterprise.

 

Parameters

Provide the package_id of the signed document to delete.