Basic concepts
You need to understand the basic structure of how our system is organized and what parameters you have control over while sending documents for signature through our APIs. This section explains the basic concepts that are involved in using Zoho Sign.
Documents
Documents in Zoho Sign are the signature requests that you create and send out for signature. Every document has a unique ID that you obtain when you create the document. This document ID has to be passed through the request_id key in all API calls.
Each document has the following parts:
- Files: Multiple files can be added to a document. A document must have at least one file associated with it before it is sent.
- Actions: Actions are the recipients who are part of the signature workflow. A document must have at least on action, or signer, before it is sent.
Document-related details
| Data Key | Description | Modifiable |
| request_name * | The name of the document | Yes |
| request_type_id * | The document type of the document | Yes |
| request_type_name * | The name of the associated document type | No |
| notes | Notes are sent to all recipients | Yes |
| is_sequential * | Whether the document is sent to the recipients in order | Yes |
| expiration_days * | The number of days after which the document will expire and cannot be signed | Yes |
| email_reminders | Whether to remind signers that they need to sign the document | Yes |
| reminder_period | The interval to remind signers at in number of days | Yes |
| folder_id | The ID of the folder to associate the document with | Yes |
| documents | The list of files and file details associated with this document. This will be a JSON array with one JSON object for each file. | Yes |
| actions * | The list of ctions associated with this document. This is the recipients who are part of the signature flow. This is a JSON array with one JSON object for each action. | Yes |
| request_status | The status the document is in. This is automatically updated based on user actions. | No |
| created_time | The time the document was created | No |
| modified_time | The time the document was last modified | No |
| sign_submitted_time | The time the document was sent for signature.Only for documents with the status in progress,completed,expired,declined,or recalled. | No |
| action_time | Time the last user action was performed, for example, the last signature on the document or the time it was recalled or declined. | No |
| self_sign | Whether the document is to be signed by yourself only | Yes |
| description | Description of the document | Yes |
| owner_email | Email address of the document owner.Automatically populated with the API user's email address. | No |
| owner_first_name | First name of the document owner.Automatically populated with the API user's name. | No |
| owner_last_name | Last name of the document owner.Automatically populated with the API user's name. | No |
| sign_percentage | Percentage of completion of the signing process.Only available for in progress and completed documents. | No |
| deleted_actions | An array of action_ids in case you need to delete any recipients that have been added. This is only to be sent and will not be returned from the server. | Yes |
Files
Files are parts of the Zoho Sign document. Every document can have up to 10 files. Every file has a unique ID. This ID is found in the document_id key in API calls and responses. The ID is generated by the system when you upload the files and is returned in the response.
| Data Key | Description | Modifiable |
| document_id * | Unique ID associated with the file | No |
| document_name * | File name with extension | No |
| document_size | File size in bytes | No |
| total_pages | The number of pages in the file | No |
| document_order | The order of the document in the signature request, starting from 0. This is automatically assigned based on the order the document is uploaded and can be modified when updating the document. | Yes |
You can use the APIs to upload a file and the other details will be calculated by the system. The order of the documents can be modified.
Actions
Actions are the recipients who are part of the document signing workflow. Each action has a unique ID as part of the "action_id". The ID is generated by the system automatically when you first add the recipient. The action_id must be specified any time modifications are made to the recipient details.
There are three types of recipients in Zoho Sign, and the recipient type is specified in the API using the "action_type" key. These are the recipient types and their action_type values:
| Recipient Type | Description | action_type |
| Signer | Recipient who has to sign the document | SIGN |
| Receives a copy | The recipient only receives a copy of the document to view. No action to be performed. | VIEW |
| In-person signer | Recipient who is signing in person using the device of another Zoho Sign user in the organization | INPERSONSIGN |
| Data Key | Description | Modifiable |
| action_id (auto generated) | Unique ID of the action | No |
| recipient_name * | Name of recipient. Name of host if the action type is INPERSONSIGN | Yes |
| recipient_email * | Email address of recipient | Yes |
| action_type * | Type of recipient as specified in the table | Yes |
| private_note | Message to be sent privately to a particular recipient | Yes |
| signing_order * | Integer indicating the order of the recipient in the signing process | Yes |
| verify_recipient * | Boolean indicating whether a verification code has been set for the recipient | Yes |
| verification_type | Type of verification set for the recipient: EMAIL, OFFLINE, or SMS | Yes |
| verification_code | Verification code to be used if the verification type is OFFLINE | Yes |
| recipient_phonenumber | Phone number of the recipient: required if SMS verification is used | Yes |
| recipient_countrycode | Country code of recipient's phone number: required if SMS verification is used | Yes |
| is_revoked | Whether the recipient's access has been due to entering the wrong code three times | No |
| action_status | Current status of the recipient indicating whether they have viewed or signed the document: UNOPENED, VIEWED, or SIGNED | No |
| in_person_name | Name of the in-person signer if the action type is INPERSONSIGN | Yes |
| in_person_email | Email id of the in-person signer in case the action type is INPERSONSIGN | Yes |
| is_host | This is true if the action is in-person signature | No |
| fields * | The details of the fields assigned to this recipient. Does not apply to action_type VIEW. A JSON array where each object contains field details. | Yes |
Field coordinate system
The coordinates of fields added in Zoho Sign must be specified. The coordinate system of documents has the origin positioned at the top left corner of the PDF. We allow any positive dimension to be specified from (0,0) and the field will be placed at the appropriate location. If the field exceeds the width or height of the page, you will not be able to view the field but it will be placed.
The range of visible coordinates depends on the width and orientation of the page. For example, an A4 size page in portrait orientation has a width of 595 and height of 842. A different paper size and different coordinates on the page would result in a different position.
Fields
Fields are added to Zoho Sign documents for signers to fill in data when they sign the document using Zoho Sign. Zoho Sign supports these field types:
| Field | Description | API Name | Field Category |
| Signature | Signature of the signer | Signature | image |
| Initial | Initials of the signer | Initial | image |
| Email address of the signer (filled automatically) | textfield | ||
| Company | Company name of signer | Company | textfield |
| Job title | Job title of the signer | Jobtitle | textfield |
| Sign date | Date of signing the document (filled automatically) | Date | datefield |
| Text field | Any text field | Textfield | textfield |
| Full name | Full names of signers (filled automatically for people with Zoho Sign accounts) | Name | textfield |
| Check box | A check box field that users can choose to check or uncheck | Checkbox | checkbox |
| Attachment | An attachment field to add supporting document | Attachment | filefield |
| Date | Field to get dates from signers (ex DOB, DOJ) | CustomDate | datefield |
Fields of any type can be added to documents as part of a particular action.
Each type of field has a unique ID that is specific to each Zoho Sign account. The ID for a particular account can be retrieved using the call to get field type. Each field has a unique field_id that is autogenerated by Zoho Sign once the field has been added to the document.
Every field contains the following information:
| Data Key | Description | Applies To |
| field_id (autogenerated) | Unique ID of the field. Autogenerated and cannot be modified. | All fields |
| field_type_id | The ID for the field type | All fields |
| field_name* | The name of the field to be added | All fields |
| field_label* | The label of the field | All fields |
| action_id * | The ID of the action the field needs to be added to | All fields |
| x_coord * | The x coordinate of the location where the field is to be placed | All fields |
| y_coord * | The Y coordinate of the place where the field is to be placed | All fields |
| abs_width * | Width of the field in terms of the coordinate system | All fields |
| abs_height * | Height of the field in terms of the coordinate system | All fields |
| is_mandatory * | Whether or not the field is mandatory. If this is false, users do not have to fill in this field. | Text fields and check boxes. Other fields are always mandatory |
| document_id * | The ID of the file the field is to be placed on | All fields |
| page_no * | Page number of the field | All fields |
| action_id | Action ID of the recipient to assignthe field to | All fields |
| field_category * | Category of the field: textfield, image, checkbox, or datefield. Automatically set by the system. | All fields |
| is_read_only | Whether the field is read-only or not. If the field is read-only, a default value must be set. | Text fields and check boxes |
| default_value | The default value of the field. True or false for check boxes, any text for text fields | Text fields and check boxes |
| name_format | Format of the full name field: FIRST_NAME, LAST_NAME, or FULL_NAME | Full name field |
| date_format | Format of the date to be displayed | Sign date |
| description_tooltip | Description of the field that would be shown as a tool tip | All fields |
| text_property | Text formatting properties | Text fields and date fields |
Text and date type fields have additional text properties associated with them for formatting the text. This ensures you can format these fields to appear to match the document contents. This is part of the text_property object of the field data.
| Data Key | Description |
| font | Name of the font to be used |
| font_size | Integer indicating the font size to be applied |
| font_color | The font color to be used as the hex code (e.g.- 000000 for black) |
| is_bold | Indicates whether the text is bold |
| is_italic | Indicating whether the text is italic |
Changes can be made to any field by passing the field properties along with the previously generated field_id property.
Templates
Templates in Zoho Sign are commonly used documents which are saved with placeholders for recipients and fields already added and set up. These can be easily used at the time of sending giving only the recipient details and any data to be prefilled.
- Templates have all the data related to documents as mentioned in previous sections.
- There are a few small differences between the attributes of documents and templates.
- template_name is used instead of request_name for a template.
- document_fields - this is a JSON array used to define Prefill fields. Each JSON object in the array represents each of the files in the document. The attributes of each object are :
| Data Key | Description | Modifiable |
| document_id * | ID of the document associated with this field | Yes |
| fields * | A JSON array with the details of the fields to be prefilled | Yes |
| deleted_fields | If any prefill fields have been deleted, their IDs will need to be included here | Yes |
In addition to those, each action can also have the following additional attributes.
| Data Key | Description | Modificable |
| role | A placeholder role to be added to the template. This will be filled when using the template | Yes |
When using a template, you will need to send the details about each action similar to what is done with sending documents for signature. In addition to this if there are prefill fields, then you will need to send those as well.