Sign a document with form fields
Overview
Some business workflows generate documents that the Signer must fill out 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
To populate fields on a document, the developer must know what the name of the field is.
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 sends it to SigningHub. Fields with known values are populated and the fields with unknown values can be left for the Signer to fill out.
SigningHub date fields on the document will be auto-populated at the time of signing.
Process flow
At a high level, the sample code
will perform the following steps:
-
Prepares the workflow.
-
Populates the fields on the
document.
-
Draws any additional fields.
-
Shares the document.
-
SigningHub sends email
notification to Signer.
-
Signer logs into SigningHub.
-
Signer fills out required
fields
-
Signer signs the document.
-
Third-party application checks the document status.
-
Third-party application
downloads the signed document.
-
Third-party downloads the
forensic Workflow Evidence report.
-
Deletes the document.
Requests
The following requests share a document with one Signer and update a textfield on the document.
Step 1 – Authenticate
|
Overview
|
|
Authenticate to SigningHub.
|
|
Online Documentation
|
|
https://uatweb.signinghub.co.za/manuals/signinghub/api-guide/v3/1010.htm
|
|
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. The package acts as an envelope that contains the documents to sign and the workflow rules.
|
|
Online Documentation
|
|
https://uatweb.signinghub.co.za/manuals/signinghub/api-guide/v3/1020.htm
|
|
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://uatweb.signinghub.co.za/manuals/signinghub/api-guide/v3/1022.htm
|
|
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://uatweb.signinghub.co.za/manuals/signinghub/api-guide/v3/1047.htm
|
|
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.
If additional security is specified, the user will now have to enter a password or 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://uatweb.signinghub.co.za/manuals/signinghub/api-guide/v3/1182.htm
|
|
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 for the first Signer.
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 parameter placement is used to position the signature block relative to the search_text.
The dimension parameter controls the size of the signature block.
The Order parameter corresponds to the Signer’s order in which he/she must sign. Set the value to 1.
Set the Field_type to
"ELECTRONIC_SIGNATURE".
|
Step 6 – Update form field
|
Overview
|
|
Set the value
of a form field on the document.
|
|
Online Documentation
|
|
https://uatweb.signinghub.co.za/manuals/signinghub/api-guide/v3/1081.htm
|
|
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://uatweb.signinghub.co.za/manuals/signinghub/api-guide/v3/1073.htm
|
|
Description
|
|
This request places a date field
on the document at the specified location.
The date field is automatically 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 dimension parameter controls the size of the date field.
Order corresponds to the
Signer’s order in which he / she must sign. Set the value to 1.
Set the parameter field_type to "DATE".
|
Step 8 – Share document
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/1160.htm
|
|
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/1164.htm
|
|
Description
|
|
The Signer manually signs the
document.
|
|
Parameters
|
|
N/A
|
Step 9 – Get document status (Optional)
|
Overview
|
|
Get the workflow status.
|
|
Online Documentation
|
|
https://uatweb.signinghub.co.za/manuals/signinghub/api-guide/v3/1044.htm
|
|
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
Step 11 – Download Workflow Evidence report
(Optional)
|
Overview
|
|
Download the forensic Workflow
Evidence Report document.
|
|
Online Documentation
|
|
https://uatweb.signinghub.co.za/manuals/signinghub/api-guide/v3/1045.htm
|
|
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