​

Submit request in Zoho Sign

Table of Contents

Note:

  • Each time the zoho.sign.submitRequest integration task is executed, it triggers an API request in the back-end. This call is deducted from the external calls limit available for the service from which the task is executed, based on your pricing plan.
  • Only actual executions that receive a response (whether success or failure) are counted, not the number of times the task appears in the script. For example, if zoho.sign.submitRequest integration task is placed inside a for each task that iterates five times, the number of external calls consumed will be five, even though the task appears only once in the script. 

Overview

The zoho.sign.submitRequest task is used to insert required fields into documents and send them out to the specified recipients.

Syntax

<response> = zoho.sign.submitRequest(<request_id>, <params>, [<connection>]);

where,

ParamsData TypeDescription
<response>KEY-VALUEThe status of the executed task, document details, recipient details, and other relevant information.
<request_id>NUMBER

The request ID of the document that needs to be downloaded.

Note: You can get the ID of the Zoho Sign request from its URL. The URL is in the format: https://sign.zoho.com/zs#/request/new/<request_id>
(or)
You can get the request ID from the response of zoho.sign.uploadDocument task. Click here to learn how to fetch request ID from the response.

<params>KEY-VALUEThe details of the documents, fields, and the recipients.

<connection>

(optional)*

TEXT

The name of the connection.

*Note: This param is not applicable to Zoho Creator and mandatory in Zoho Cliq.

Example

The following script adds fields to a document in Zoho Sign and emails it to a recipient to get it signed.

 // Create a map to store the details of the signature field
 fieldsMap = Map();
 fieldsMap.put("x_coord", "402");
 fieldsMap.put("field_type_id", "10696000000000047");
 fieldsMap.put("abs_height", "20");
 fieldsMap.put("field_category", "image");
 fieldsMap.put("field_label", "Signature");
 fieldsMap.put("is_mandatory", "true");
 fieldsMap.put("page_no", "0");
 fieldsMap.put("document_id", "10696000000010242");
 fieldsMap.put("field_name", "Signature");
 fieldsMap.put("field_type_name", "Signature");
 
 // Create a list to store all the fields that need to be inserted
 fieldList = List();
 fieldList.add(fieldsMap);
 
 // Create a map to store the details of the first recipient
 actionMap = Map();
 actionMap.put("fields", fieldList);
 actionMap.put("recipient_name", "Shawn");
 actionMap.put("recipient_email", "shawn@zylker.com");
 actionMap.put("action_type", "SIGN");
 actionMap.put("signing_order", 0);
 
 // Create a list to store all the recipients of the document
 actionList = List();
 actionList.add(actionMap);
 
 //Create a map to store the request details 
 requestMap = Map(); 
 requestMap.put("request_name", "Agreement"); 
 requestMap.put("actions", actionList); 
 
 // Store the request details as a value to the key - data 
 dataMap = Map(); 
 dataMap.put("data", {"requests": requestMap}); 
 
 // Perform submit request task to insert fields and send the document to the specified recipients
 response = zoho.sign.submitRequest(10696000000010248, dataMap);

where:

response
The KEY-VALUE response that holds the details of the recipients and documents that are sent out to sign.
fieldsMap 
actionMap 
requestMap 
dataMap 
The KEY-VALUE pairs which hold the required information to submit the request.
fieldList 
actionList 
The LIST variables that holds the list of fields and recipients.
10696000000010242
The NUMBER that represents the ID of the document into which the signature field needs to be inserted.
10696000000000047
The NUMBER that represents the ID of the signature field.
10696000000010248
The NUMBER that represents the request ID.
Note: You can get the field_type_id from the response of zoho.sign.getFieldIds task. Click here to learn more about it.

Response Format

  • Success Response

  • The success response will be returned in the following format:

     {
     "code": 0,
     "requests": {
     "request_status": "inprogress",
     "notes": "",
     "attachments": [
     
     ],
     "reminder_period": 5,
     "owner_id": "10696000000009003",
     "description": "",
     "request_name": "ReqestName",
     "modified_time": 1575553781979,
     "action_time": 1575553782054,
     "is_deleted": false,
     "expiration_days": 15,
     "is_sequential": true,
     "sign_submitted_time": 1575553782054,
     "owner_first_name": "Shawn",
     "sign_percentage": 16.67,
     "expire_by": 1576866540000,
     "is_expiring": false,
     "owner_email": "shawn@zylker.com",
     "created_time": 1573034420841,
     "email_reminders": true,
     "document_ids": [
     {
     "document_name": "Agreement_1.jpg",
     "document_size": 1095706,
     "document_order": "0",
     "total_pages": 1,
     "document_id": "10696000000013005"
     },
     {
     "document_name": "Agreement_2.png",
     "document_size": 96995,
     "document_order": "1",
     "total_pages": 1,
     "document_id": "10696000000013008"
     }
     ],
     "self_sign": false,
     "in_process": false,
     "validity": -1,
     "request_type_name": "Others",
     "request_id": "10696000000013017",
     "request_type_id": "10696000000000187",
     "owner_last_name": "Shawn",
     "actions": [
     {
     "verify_recipient": false,
     "action_type": "SIGN",
     "private_notes": "",
     "recipient_email": "shawn@zylker.com",
     "allow_signing": true,
     "recipient_phonenumber": "",
     "is_bulk": false,
     "action_id": "10696000000013021",
     "is_revoked": false,
     "is_embedded": false,
     "signing_order": 1,
     "fields": [
     {
     "field_id": "10696000000013024",
     "x_coord": 431,
     "field_type_id": "10696000000000047",
     "abs_height": 20,
     "field_category": "image",
     "field_label": "Signature",
     "is_mandatory": true,
     "page_no": 0,
     "document_id": "10696000000013005",
     "field_name": "Signature",
     "y_value": 78.76336,
     "abs_width": 135,
     "action_id": "10696000000013021",
     "width": 22.689075,
     "y_coord": 663,
     "field_type_name": "Signature",
     "description_tooltip": "",
     "x_value": 72.43435,
     "height": 2.375297
     }
     ],
     "recipient_name": "Shawn",
     "action_status": "NOACTION",
     "recipient_countrycode": ""
     },
     {
     "verify_recipient": false,
     "action_type": "SIGN",
     "recipient_email": "shawn@zylker.com",
     "allow_signing": true,
     "recipient_phonenumber": "",
     "is_bulk": false,
     "action_id": "10696000000027002",
     "is_revoked": false,
     "is_embedded": false,
     "signing_order": -1,
     "fields": [
     {
     "field_id": "10696000000027005",
     "x_coord": 402,
     "field_type_id": "10696000000000047",
     "abs_height": 20,
     "field_category": "image",
     "field_label": "Signature",
     "is_mandatory": true,
     "page_no": 0,
     "document_id": "10696000000013005",
     "field_name": "Signature",
     "action_id": "10696000000027002",
     "field_type_name": "Signature",
     "description_tooltip": ""
     }
     ],
     "recipient_name": "Shawn",
     "action_status": "UNOPENED",
     "recipient_countrycode": ""
     }
     ],
     "attachment_size": 0
     },
     "message": "Document has been submitted and sent for signature",
     "status": "success"
     }

Failure Response

  • The failure response for an incorrect or inaccessible document will be returned in the following format:

     {
     "code":4003,
     "message":"Access to view the document is denied",
     "status":"failure"
     }

Related Links