Documents

This section describes the documents to be filled or signed during the entire workflow. Each document is a JSON array containing JSON objects, each object corresponds to a single document. Table 1 describes the document parameters.

Table 1: Document Parameters

Parameter	Type	Optional/Required	Discerption
id	string	Optional	An internal random identifier for a document
title	string	Required	The title of the document
file	object	Required	Describes the content of the document to be signed NOTE For additional information about the File Descriptor Syntax section, click here
fieldDetectionType	string	Required	One of the following preset values: autoDetect NOTE For additional information about auto-detect, click here whiteOnwhiteDetect NOTE For additional information about white-on-white-detect, click here selfAssignedDetect NOTE For additional information about self-assigned-detect, click here

File Descriptor Syntax

Table 2 describes the file descriptor syntax parameter.

Table 2: File Descriptor Syntax Parameter

Parameter

Type

Optional/Required

Discerption

type

string

Required

One of the following preset values:

url - used for sending the file using a publicly available URL

NOTE

For additional information about the url type, click here

s3 - used for fetching the file from a public/private Amazon S3 bucket

NOTE

For additional information about the s3 type, click here

base64 - used for providing the entire document encoded in base64 as a part of the request

NOTE

For additional information about the base64 type, click here

File Descriptor Syntax - url

Table 3 describes the url parameter.

Table 3: url Parameter

Parameter	Type	Optional/Required	Discerption
url	string	Required	A publicly accessible url containing the PDF document.

File Descriptor Syntax - s3

Table 4 describes the s3 parameters.

Table 4: s3 Parameters

Parameter	Type	Optional/Required	Discerption
bucket	string	Required	The name of the Amazon Web Services S3 Bucket containing the PDF document.
path	string	Required	Path for the document inside this Amazon Web Services S3 bucket

NOTE

If the bucket is not publicly accessible, EasySend will need to configure an AWS user account to access the bucket. Please contact EasySend’s support team to set this up.

File Descriptor Syntax - base64

Table 5 describes the based64 parameter.

Table 5: base64 Parameter

Parameter	Type	Optional/Required	Discerption
data	string	Required	The base64 encoded content of the PDF document

Field Detection Type - autoDetect

This mode uses field annotations based on standard PDF field annotations. The PDF file format supports describing editable fields on top of the document. Using the auto-detect mode, EasySend will automatically detect these fields and make them available for editing, without having to manually describe them as a part of the API call. This mode is useful for documents that were generated using software that allows the definition of these dynamically editable fields on top of the PDF document (such as Adobe Acrobat DC). This mode does not require any additional fields.

Field Detection Type - whiteOnWhiteDetect

This mode uses special text paragraphs on top of the document to describe the location and information of the fields on top of the document. This text is typically “hidden” on top of the document (written in white text on top of a white background) so that it can be detected by EasySend and is not visible to the user. The whiteOnWhiteDetect mode is especially useful for documents that were generated automatically by a document generation system that does not support standard PDF field annotations. Using this mode, we still get the benefit of dynamically locating fields on top of the document without having to provide exact pixel locations, while still supporting document generation systems that don’t support dynamic PDF fields.

The “whiteOnWhiteDetect'' detects text boxes in the document that contain a special text prefix “$EASYSEND:”. This allows you to define fields on top of the document that are recognized by the EasySign:

The text should begin with $EASYSEND following a : ($EASYSEND:) and then either a JSON object or an Id:
- For a JSON object - the /json should contain the protperties of the field
- For a JSON object - the JSON should contain the properties of the field
- For an Id - The object will map the id to its properties

In this mode, the linkedIds array is required as a part of the document object (see Table 6):

Table 6: linkedIds Parameter

Parameter

Type

Optional/Required

Discerption

linkedIds

array

Required

An array of objects, containing two fields:

id - referencing the Id encoded for the field in the document
value - specifying more information about the field

NOTE

For additional information about value, click here.

Field Detection Type - whiteOnWhiteDetect - value

Table 7 describes the value parameters.

Table 7: value Parameters

Parameter	Type	Optional/Required	Discerption
type	many	Required	signature text xMarker - used for checkboxes signDate - used to show a read-only date related to the signature field
role	string	Required	Specifies the role of the participant that should fill out the field, if no role is specified, any participant is allowed to fill out the field
required	boolean	Required	Specifies whether the field is required or not, set to false by default
forField	string	Optional	The date when the signature field was last updated
defaultValue	string	Optional	Allows the API call to provide an initial value for the field, that can later be edited by the user, the value is determined according to the type of the field: text - string xMarker - boolean signature - no value
groupValue	string	Optional	When the field indicates a selection of one option out of multiple possibilities, separate fields should be defined for each option and value

Sample Call

Field Detection Type - selfAssignedDetect

Allows the user to manually provide field locations and information as a part of the API call. This is useful for documents that we cannot control (for example cannot be edited), but still want to allow a digital signature/interactive field editing on top of the document.

In this mode an additional array is required as a part of the document object (see Table 8):

Table 8: selfAssignedDetect Parameter

Parameter

Type

Optional/Required

Discerption

docFields

array of arrays

Required

An array containing an additional array for every page of the document

NOTE

For additional information about docFields, click here.

Field Detection Type - selfAssignedDetect - docFields

Table 9 describes docFields parameters.

Table 9: docFields Parameters

Parameter	Type	Optional/Required	Discerption
label	string	Required	The name of the field
type	many	Required	signature text xMarker - used for checkboxes signDate - used to show a read-only date related to the signature field
multiline	boolean	Optional	If set to true, creates a multiline input field
groupValue	string	Optional	When the field indicates a selection of one option out of multiple possibilities, separate fields should be defined for each option and value
name	string	Optional	The value will be used as the id of the field NOTE For internal usage
fontSize	string	Optional	The font size of the text field
isRequired	boolean	Optional	If set to true, sets the field as required
position	object	Required	Contains the field coordinates: left top width height
role	string	Optional	Specifies the role of the participant that should fill out the field, if no role is specified, any participant is allowed to fill out the field