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
At a high level, the sample code
will perform the following steps:
-
Prepare the workflow.
-
Share the document.
-
Signer 1 logs into the
third-party application.
-
The document is displayed to
the Signer using the SigningHub iFrame.
-
Signers signs the document.
-
The third-party checks the
status of the document.
-
If the document status is
“Complete”, the signed document is downloaded.
-
The Workflow evidence report is
downloaded.
-
The signed document is deleted
from SigningHub.
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
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
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