Bulk Sign

Purpose

This API allows the merge and sign documents in bulk.

HTTP Request URL

https://{zohoapis_domain}/writer/api/v1/templates/{{template_id}}/bulkmerge/sign

Path Parameters

Parameter	Data Type	Description
Mandatory Parameters
document_id	String	Specify a unique id for the writer document.

Body Parameters

Parameter	Data Type	Description
Mandatory Parameters
filename	String	Specify a unique name for the signed document.This can be achieved using anyone of the following ways; 1. You can pass it has a normal string value. For example: filename=NDA_Agreement (OR) 2. You can also customise the filename for each recipients by passing the merge field id. For example: filename=NDA_Agreement <<ClientName>> Maximum length allowed: 150
signer_data	[ { "recipient_1":{type:'field',field_id:'email'}, "action_type”:<approve\|sign\|view> }, { "recipient_2":{type:'email', email_id:'john@zylker.com'}, "action_type”:<approve\|sign\|view> }, ... ]	Specify the recipients to whom the document needs to be sent to get signed, approved or viewed in the form of a JSON Array. The recipients email id can either be a merge field specified in the 'merge_data' param(eg: recipient_1: { type: field, 'field_id': 'email') or an email address (eg: recipient_2 : {'type': email, 'email_id' :john@zylker.com).
You can provide the data in any one of the below formats
merge_data	JSONObject	Pass a String value through 'data' key as JSON Array.
merge_data_csv_content	File	Provide the required csv content in your API request body.
merge_data_json_content	File	Provide the required json content in your API request body.
merge_data_csv_url	url	Provide the required csv url in your API request body.
merge_data_json_url	url	Provide the required json url in your API request body.
Optional Parameters
sign_in_order	Boolean (true / false)	Specify if we need to maintain the order of signing as mentioned.
message_plaintext (or) message_richtext	String (or) HTML	Specify any message for the signer either in the form of a plaintext or a HTML. Supported HTML tags are listed here .
set_expire	Number	Specify when the merged documents which are sent for sign needs to be expired.
reminder_period	Number	Specify the interval when the remainder email needs to be send to the signers.
language	String	Specify the language in which the notification email needs to be sent to the signers. Supported languages are: Chinese(zh), Dutch(nl), English(en), French(fr), German(de), Italian(it), Japanese(ja), Polish(pl), Portuguese(pt), Russian(ru), Spanish(es), Swedish(sv).
common_attachments	String	Specify the attachments that needs to be sent to all the recipients in common. Maximum files allowed: 3 Maximum file size allowed: 3MB Supported file formats:docx / doc / rtf / pdf / zip / html / txt / png / jpeg / gif / jpg

signer_data

Parameter

Type

Possible Values

Default Value

recipient_n

JSON

recipient_1, recipient_2, ... , recipient_10

Note: Upto 10 recipients are supported as of now.

john@zylker.com

action_type

string

approve/sign/view

sign

JSON values

Keys	Type	Possible Values
type	string	field/email
field_id	string	Any one of the field provided in the 'merge_data' param.
email_id	email	john@zylker.com

language

Parameter

Type

Possible Values

Default Value

language

string

en / 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.

Note:

To use this API, an OAuth token should be generated with the following scopes ZohoWriter.documentEditor.ALL, ZohoWriter.merge.ALL and ZohoSign.documents.ALL
Check out the prerequisites needed to make the Bulk Sign API work, here.
We have also provided an option to configure the values for all the above parameters while creating the document itself.
If you have saved the merge settings earlier by configuring the parameter values, then we will get those values (by default) if you miss to pass the parameters while sending the API request.
In Writer, we achieve the 'Digital Signature' by using our Zoho Sign API internally. The credits will be consumed based on the Zoho Sign API subscription plan. For more details, please refer this link.

Sample Request


				curl --location --request POST "https://zohoapis.com/writer/api/v1/templates/ponazfea04477109f4681a831e7177d96bc40/bulkmerge/sign" \
  --header "Authorization: Zoho-oauthtoken xxx.yyy.zzz" \
  --form "filename=New Document" \
  --form "signer_data=[{\”recipient_1\”:{type:'field',field_id:'email'},\”action_type\”:\”sign\”},{\”recipient_2\”:{type:'email',email_id:’john@zylker.com’},\”action_type\”:\”approve\”}]" \
  --form "merge_data={\"data\":[{\"name\":\"John\",\"email\":\"john@zylker.com\"},{\"name\":\"Amelia\",\"email\":\"amelia@zylker.com\"}]}"

Sample Response


				{
    "merge_report_data_url": "http://writer.zoho.com/writer/api/v1/merge/job/0tq5n465132106580437abe99b6f56f2b0c85/data",
    "merge_report_url": "http://writer.zoho.com/writer/v1/mailmerge/job/0tq5n465132106580437abe99b6f56f2b0c85",
    "records": [
        {
            “name”:“John”,
            "email": "john@zylker.com",
            "download_link": "{url}",
            "status": "inprogress"
        },
        {
            “name”:“Amelia”,
            "email": "amelia@zylker.com",
            "download_link": "{url}",
            "status": "inprogress"
        }
    ]
}