--- title: "Documents" slug: "documents" updated: 2024-08-12T09:34:10Z published: 2024-08-12T09:34:10Z canonical: "kb.easysend.io/documents" --- > ## Documentation Index > Fetch the complete documentation index at: https://kb.easysend.io/llms.txt > Use this file to discover all available pages before exploring further. # Documents ## 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 signedNOTEFor additional information about the File Descriptor Syntax section, click [here](/v1/docs/documents#file-descriptor-syntax) | | fieldDetectionType | string | Required | One of the following preset values: - autoDetect NOTEFor additional information about auto-detect, click [here](/v1/docs/documents#field-detection-type-autodetect) - whiteOnwhiteDetect NOTEFor additional information about white-on-white-detect, click [here](/v1/docs/documents#field-detection-type-whiteonwhitedetect-value) - selfAssignedDetect NOTEFor additional information about self-assigned-detect, click [here](/v1/docs/documents#field-detection-type-selfassigneddetect) | ### File Descriptor Syntax **T****able 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 NOTEFor additional information about the url type, click [here](/v1/docs/documents#file-descriptor-syntax-url) - s3 - used for fetching the file from a public/private Amazon S3 bucket NOTEFor additional information about the s3 type, click [here](/v1/docs/documents#file-descriptor-syntax-s3) - base64 - used for providing the entire document encoded in base64 as a part of the request NOTEFor additional information about the base64 type, click [here](/v1/docs/documents#file-descriptor-syntax-base64) | ### File Descriptor Syntax - url **T****able 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 **T****able 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 | NOTEIf 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 **T****able 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. ![](https://cdn.document360.io/45e1a1b1-1964-46f1-939e-f40bde9b50fa/Images/Documentation/image-1723454639292.png) ### 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 ![](https://cdn.document360.io/45e1a1b1-1964-46f1-939e-f40bde9b50fa/Images/Documentation/image-1723455054280.png) 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 NOTEFor additional information about [value](/v1/docs/documents#field-detection-type-whiteonwhitedetect-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 ![](https://cdn.document360.io/45e1a1b1-1964-46f1-939e-f40bde9b50fa/Images/Documentation/image-1723455098311.png) ### 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 NOTEFor additional information about docFields, click [here](/v1/docs/documents#field-detection-type-selfassigneddetect-docfields). | ### Field Detection Type - selfAssignedDetect - docFields **T****able 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 NOTEFor 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 | ### Sample Call ![](https://cdn.document360.io/45e1a1b1-1964-46f1-939e-f40bde9b50fa/Images/Documentation/image-1723455227938.png)