Choose where you’d like to start

Merge and Sign in Zoho Writer

Table of Contents

Description

The zoho.writer.mergeAndSign task merges your document and sends it to recipients for signature collection. This task is based on the Zoho Writer Merge and Sign API.

Note: Applicable to all services except Zoho Creator.

Syntax

<response> = zoho.writer.mergeAndSign(<document_id>, <merge_detail>, <filename>, <signerList>, <option_settings>,  <connection>)

where:

ParamsData typeDescription
<response>KEY-VALUEThe response returned by Zoho Writer. It provides the merged document's details such as the merge data, along with the status of the merge.
<document_id>TEXT

The ID of the document to be merged and sent for signature.

The document ID can be obtained from the URL of the document which needs to be merged and sent for sign.

The URL is formatted as follows:
https://writer.zoho.com/writer/open/<document_id>

<merge_detail>KEY-VALUE Specify how your input for the merge will be. It can be JSON, CSV file, or a URL.
<filename>StringA unique name for the signed document.
<signerList>

[
{
"recipient_1": "john@zylker.com",
"action_type": <approve|sign|view|in_person_sign>,
"language": "en”,
“private_notes”: “Hey! Please sign this document”
},
{
"recipient_2": "amelia@zylker.com",
"action_type": <approve|sign|view|in_person_sign>,
"language": "fr",
“verification_info": {
"type": <email|sms|offline>
}
},
...
]

The recipients to whom the document will be sent for signature, in-person signing, or viewing and approval in the form of a JSON Array.

 

You can also set the language for the notification email that will be sent to signers. You can authenticate and provide private notes to recipients.

 

Supported languages:

Chinese(zh), Dutch(nl), English(en), French(fr), German(de), Italian(it), Japanese(ja), Polish(pl), Portuguese(pt), Russian(ru), Spanish(es), Swedish(sv).

 

You can refer to a sample JSON Array here.

 

Note: If this parameter is not passed, we will apply the values configured in the template settings.

<optional_settings>KEY-VALUEThe optional parameters you can send to merge and sign data according to your preference.
<connection>TEXT

The connection's link name.

Note:

  • To prevent new authtoken generation and ensure new integration tasks (tasks created after the deadline specified in the post) work as expected, a Zoho OAuth connection with appropriate scopes is mandatory. Existing integration tasks will continue to work, with or without the connections parameter, until you manually delete the authtoken from Zoho Accounts

  • Add relevant scopes from the Zoho Writer API when creating the connection.

  • Refer to this post for a list of Zoho services that support the Connections page.

  • Learn more about connections

 

You can provide the merge_detail parameter in any one of the below formats:

KeyValueDescription
merge_dataJSONObjectPass a String value through data key as JSON Array.
merge_data_csv_contentFileProvide the required CSV content in your API request body.
merge_data_json_contentFileProvide the required JSON content in your API request body.
merge_data_csv_urlURLProvide the required CSV URL in your API request body.
merge_data_json_urlURLProvide the required JSON URL in your API request body.

signerList parameter values:

Parameter

Type

Possible Values

Default Value

recipient_n

string

recipient_1, recipient_2, ... , recipient_10

Note: You can send up to 10 recipients

john@zylker.com

action_type

string

approve/sign/view/in_person_sign

sign

language

string

zh/ nl / en / fr / de / it / ja / pl / pt / ru / es / sv

This option is available only for Zoho Sign Premium Plan users.

For Free Plan users, the notification email will be sent in their account language by default.

optional_settings parameter values:

Parameter

Data Type

Description

sign_in_order

Boolean (true/false)

Specify whether the signing order should be maintained as entered.

message

String

Add a message for the signer.

set_expire

Number

Specify when the merged documents which are sent for sign need to be expired.

reminder_period

Number

Specify when reminder emails should be sent to signers.

common_attachments

File

Specify the attachments that need to be sent to all the recipients in common.

Maximum files allowed: 3

Maximum file size allowed: 3 MB

Supported file formats: DOCX / DOC / RTF / PDF / ZIP / HTML / TXT / PNG / JPEG / GIF / JPG

unique_attachments

{
"type": "field",
"field_id": <field_id>
}

(OR)

}

Using this parameter, you can send a different or unique attachment to each recipient.

It can be sent in either one of the following ways:

1. Field Containing Attachment URLs: If you want to map the attachment file paths to a spreadsheet/CSV file.

(OR)

2. Folder Containing Attachments: If you want to map the attachment file paths to a particular folder.

test_mode

Boolean (true/false)

Using this parameter, you can test the Merge APIs without consuming any credit points. The output file will contain a watermark as it is used only for testing purposes.

Test mode limit: 50 merges/day for an org.

Example

The following script merges a document and sends it for approval to a user and once approved sends it for signature collection in the defined order.

document_id = "po5uobda049e029d44b13a9956f6d2cedc67b"; 

fields = Map(); 
fields.put("InvoiceNo","12345"); 
fields.put("InvoiceDate","27 May 2022"); 
fields.put("InvoiceAmount","$100");
data_map = Map();
data_map.put("data", fields)
merge_details = Map();
merge_details.put("merge_data", data_map);

filename = "Invoice data";

signerList = List(); 
signerObj1 = Map(); 
signerObj1.put("recipient_1","john@zylker.com"); 
signerObj1.put("action_type","approve");  //approve|sign|view  
signerObj1.put("language","en"); 
signerObj2 = Map(); 
signerObj2.put("recipient_2","amelia@zylker.com"); 
signerObj2.put("action_type","sign");  //approve|sign|view  
signerObj2.put("language","fr"); 
signerList.add(signerObj1); 
signerList.add(signerObj2);


commonAttachmentFile1 = invokeurl 
[ 
url :"<https://example.com/download/publicdocument>" 
type :GET 
]; 


option_settings = Map();

option_settings.put("sign_in_order","true");
option_settings.put("message", "Please find the document to be signed here");   
option_settings.put("set_expire", "30");
option_settings.put("reminder_period", "15");
option_settings.put("common_attachments", commonAttachmentFile1);
option_settings.put("test_mode", "true");

response = zoho.writer.mergeAndSign(document_id, merge_details, filename, signerList, option_settings, "writer_oauth_connection");

info response;

Usecase

Scenario 1: Send a document for signing

Consider a scenario where you need to send an offer letter for signature with all the fields configured. HR merges and creates the offer letter and sends it to the candidate for signing.

document_id = "po5uobda049e029d44b13a9956f6d2cedc67b";

fields = Map(); 
fields.put("Date","27 May 2022"); 
fields.put("Recipients_name","Mikeal"); 
fields.put("Position","Support Engineer");

data_map = Map();
data_map.put("data", fields)
merge_details = Map();
merge_details.put("merge_data", data_map);

String filename = "Offer Letter";

signerList = List(); 
signerObj1 = Map(); 
signerObj1.put("recipient_1","Hr-operations@zylker.com"); 
signerObj1.put("action_type","approve");  //approve|sign|view  
signerObj1.put("language","en"); 

signerObj2 = Map(); 
signerObj2.put("recipient_2","mikeal@test.com"); 
signerObj2.put("action_type","sign");  //approve|sign|view  
signerObj2.put("language","fr");

signerList.add(signerObj1); 
signerList.add(signerObj2);

option_settings = Map();

option_settings.put("sign_in_order","true");
option_settings.put("message", "Kindly read all the details in the document properly and accept it by signing");   
option_settings.put("set_expire", "30");
option_settings.put("reminder_period", "15");

response = zoho.writer.mergeAndSign(document_id, merge_details, filename, signerList, option_settings, "writer_oauth_connection");

info response;

Scenario 2: Collect signatures in a specific order

Consider a scenario where you need multiple people to sign a purchase order. Sales person creates the order and sends it to sales manager for approval. Once it is signed by the manager, it is sent to the client.

document_id = "po5uobda049e029d44b13a9956f6d2cedc67b"; 

fieldsList = List();

fieldsmap1 = Map(); 
fieldsmap1.put("Purchsed_Date","27 May 2022"); 
fieldsmap1.put("Product_name","Samsung series s8"); 
fieldsmap1.put("Price","50000");

fieldsmap2 = Map(); 
fieldsmap2.put("Purchsed_Date","30 May 2022"); 
fieldsmap2.put("Product_name","Apple 15 pro max"); 
fieldsmap2.put("Price","10000");

fieldsList.add(fieldsmap1);
fieldsList.add(fieldsmap2);

data_map = Map();
data_map.put("data", fields)
merge_details = Map();
merge_details.put("merge_data", data_map);

String filename = "Sales Invoice";

signerList = List(); 
signerObj1 = Map(); 
signerObj1.put("recipient_1","approval-manager@zylker.com"); 
signerObj1.put("action_type","approve");  //approve|sign|view  
signerObj1.put("language","en"); 

signerObj2 = Map(); 
signerObj2.put("recipient_2","client-manager@test.com"); 
signerObj2.put("action_type","sign");  //approve|sign|view  
signerObj2.put("language","en");

signerList.add(signerObj1); 
signerList.add(signerObj2);

option_settings = Map();

option_settings.put("sign_in_order","true");
option_settings.put("message", "Details regarding latest purchase order");   
option_settings.put("reminder_period", "15");

response = zoho.writer.mergeAndSign(document_id, merge_details, filename, signerList, option_settings, "writer_oauth_connection");

info response;

Response Format

{
    "merge_report_data_url": "http://writer.zoho.com/writer/api/v1/merge/job/po5uobda049e029d44b13a9956f6d2cedc67b/data",
    "merge_report_url": "http://writer.zoho.com/writer/v1/mailmerge/job/po5uobda049e029d44b13a9956f6d2cedc67b",
    "records": [
        {
            "InvoiceNo": "12345",
            "InvoiceDate": "27 May 2022",
            "InvoiceAmount": "$100",
            "download_link": "{url}",
            "sign_request_id":12345****",
            "status": "inprogress"
        }
    ]
}

Related Links

 

Get Started Now

Execute