Two Signer workflow
Overview
This sample code will show the
developer how to upload and share a document for two users to sign.
For this sample, both users will not
use the SigningHub interface to sign but will sign their document
programmatically.
Sample code
Download the Postman sample code.
Download the accompanying sample code documentation.
Use Case
This workflow is ideal for a procure
department that requires a contract signed by the user requesting a
service and a procurement officer before the contract is sent to a
vendor.
The signing process can be
integrated into Procurement Management software like Fraxion, SnapAP
or any other Procurement Software with integration capabilities.
Process flow
At a high level, the sample code
will perform the following steps:
-
Prepare the workflow.
-
Share the document.
-
Let Signer 1 sign the document.
-
Let Signer 2 sign the document
-
Download the signed document.
-
Download the Workflow Evidence
report.
-
Delete the document.
Requests
The following requests must be
called to share a document with two users. The digital signing
process will be completely automated.
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 first 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 – Add signer 2 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 second 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 second signer, set the value to 2.
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 6 –
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 10 – Sign
Signer 1.
|
Step 7 – Insert signature block 2
|
Overview
|
|
Draw a signature block for signer 2
on the document.
|
|
Online Documentation
|
|
https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1182.
|
|
Description
|
|
Add the name and email address of
the second person that must sign the document.
|
|
Parameters
|
|
This request will draw a signature
block on the document where the second 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 2.
Take note of the field field_name
returned from the server. The field name will be needed for Step
13 – Sign Signer 2.
|
Step 8 – Share document
Step 9 – Authenticate signer 1
|
Overview
|
|
Authenticate Signer 1 to SigningHub.
|
|
Online Documentation
|
|
https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1010.
|
|
Description
|
|
For Signer 1 to sign the document,
they must first by authenticated to SigningHub.
|
|
Parameters
|
|
Use the signer’s email address in
the username field and the signer’s password in the
password field.
The access_token will be
required during the next step Step 10 - Sign Signer 1.
|
Step 10 – Sign Signer 1
|
Overview
|
|
Sign the document.
|
|
Online Documentation
|
|
https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1087.
|
|
Description
|
|
Signer 1 signs the document in the
signature block that was drawn on the document during Step 6 –
Insert signature block.
|
|
Parameters
|
|
For a full discussion of all the
parameters in this call, please see the online documentation.
Use the access_token that was
created during Step 7 – Authenticate signer
1.
Use the value from field_name
that was created during Step 5 – Insert signature block.
Hand_signature_image: The
image passed through in this field will be placed on the document
in the field that is specified in the field_name. The image must
be a base64 string.
User_name: The email address
of the Signer.
User_password: The password
of the Signer.
The values for username and password
must the same as the ones used during Step 7 – Authenticate
signer 1.
|
Step 11 – Move workflow
Step 12 – Authenticate signer 2
|
Overview
|
|
Authenticate Signer 2 to SigningHub.
|
|
Online Documentation
|
|
https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1010.
|
|
Description
|
|
For Signer 2 to sign the document,
they must first by authenticated to SigningHub.
|
|
Parameters
|
|
Use the signer’s email address in
the username field and the signer’s password in the
password field.
The access_token will be
required during the next step Step 13 - Sign Signer 2.
|
Step 13 – Sign Signer 2
|
Overview
|
|
Sign the document.
|
|
Online Documentation
|
|
https://manuals.ascertia.com/SigningHub-apiguide/default.aspx#pageid=1087.
|
|
Description
|
|
Signer 2 signs the document in the
signature block that was drawn on the document during Step 7 –
Insert signature block.
|
|
Parameters
|
|
For a full discussion of all the
parameters in this call, please see the online documentation.
Use the access_token that was
created during Step 7 – Authenticate signer 1.
Use the value from field_name
that was created during Step 5 – Insert signature block.
Hand_signature_image: The
image passed through in this field will be placed on the document
in the field that is specified in the field_name. The image must
be a base64 string.
User_name: The email address
of the Signer.
User_password: The password
of the Signer.
The values for username and password
must the same as the ones used during Step 7 – Authenticate
signer 1.
|
Step 14 – Finish workflow
Step 15 – 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 digitally signed the
document. After calling the document’s status will be
‘Completed’.
|
|
Parameters
|
|
N/A
|
Step 16 – Download document
Step 17 – 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 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 18 – Delete document