Add Electronic Signature Field - SigningHub-APIGuide

Business applications can use this service API to add an electronic signature field to a document in a package.

At least one user must exist in a workflow before fields (input and signature) can be added to the document in this way. The order number corresponds to the recipient in the workflow. Therefore, this number must be equal or less than the total number of users in the workflow. The below example assigns this new signature field to the first person in the workflow.

See Add Users to Workflow for more information. Note if you have a document with a template applied, or have applied one using the APIs, then the workflow will already contain users.

When using electronic signatures you can enforce authentication. That is the user must input the OTP sent to their mobile device before they can sign the document. The example below shows this configuration. The OTP sent out is based upon the Service Plan of the document owner, e.g. length, and retry interval period.

https://api.signinghub.com/v3/packages/{package_id}/documents/{document_id}/fields/electronic_signature
HTTP Verb		POST
Authorization		Bearer {access_token}
Content-Type		application/json
Accept		application/json
Response Headers
Request Body		{ `"order": 1,` `"page_no": 1, "field_name": "E-Sign field", "display": "VISIBLE",` `"dimensions": {` `"x": 200,` `"y": 200,` `"width": 100,` `"height": 100` `},` `"authentication": {` `"enabled":` `true,` `"sms_otp": {` `"enabled":` `true,` `"mobile_number":` `"00445566778899"` `}` `}` `}`
Status Code	Message	Response Body
200	OK	`{` `"field_name":` `"E-Sign field"` `}`
403	Forbidden	{ `"Message":` `"You are not allowed to perform this action on locked workflow"` `}`
		`{` `"Message":` `"Account is disabled"` `}`
		`{` `"Message":` `"You are not allowed to perform the requested operation"` `}`
		`{` `"Message":` `"You cannot add fields once the document is certified and signed"` `}`
		`{` `"Message":` `"You cannot add fields once the document is locked"` `}`
500	Internal Server Error	`{` `"Message":` `"An internal server error occurred while processing the request"` `}`

The detail of each item provided in the request and response is provided below:

Item Details
Names	Description
Request Parameters:
access_token	The access token obtained as a result of successful authentication. If the "scope" parameter was used in authentication request, then this service requires the access token to be obtained using the credentials of an Enterprise admin whose enterprise role has the application integration privileges.
package_id	Package ID to which the document is added.
document_id	The document ID for which the action is to be taken.
order	The order of the user in workflow for which the signature field is being added. Note the ordering starts at '1'.
page_no	Page number on which the signature field is to be created.
field_name (optional)	Name of the field that is to be added. If not provided, system will assign an unique auto generated name to the field.
display (optional)	Visibility of the field that is to be added, possible values are "VISIBLE" and "INVISIBLE"
dimensions > x	Left location of the signature field in pixel.
dimensions > y	Top location of the signature field in pixel.
dimensions > width	Width of the signature field in pixel.
dimensions > height	Height of the signature field in pixel.
authentication > enabled	True, if authentication is enabled for the signature field. False otherwise. Note this is a mandatory field.
authentication > sms_otp > enabled	True, if SMS OTP authentication is enabled for the signature field. False otherwise. Note this is a mandatory field.
mobile_number	Mobile number of the recipient to which the signature field is assigned. If authentication is not required and designated as 'false' then an empty string argument, i.e. "", is required. This is a mandatory field.
Response Parameters:
field_name	Name of the field created in the document.
Message	The service specific error message returned by the API. This message provides useful information about why the service has returned an error response.