Edit Fillable Template

Purpose

Edit a fillable template in Zoho Writer. Users can upload an existing fillable template from their local drive or a publicly accessible Web URL and edit it online.

Quick Reference

Property	Value
Method	POST
Request URL	https://{api.office-integrator_domain}/writer/officeapi/v1/fillabletemplates
Content-Type	multipart/form-data

Parameters

Body Parameters

Parameter	Value	Mandatory/Optional	Description
apikey	423s*****	Mandatory	Uniquely identifies the web application in which the Writer editor is integrated.
document or url	File or String	Mandatory	Method of providing the input file depending on its location. document - if the input file is from your local drive or desktop. url - if the input file is from a publicly accessible Web URL. Supported file formats during import: zfdoc, zdoc, doc, docx, rtf, odt, htm, html, txt and pdf.
callback_settings	{ "save_url":<Your Save URL>, "http_method_type": "post", "retries": <Integer>, "timeout": <Integer>, "save_url_params": { .... } }	Mandatory	Using this param, you will be able to specify the following; save_url -> Provide your server location to which the latest content needs to be pushed back when the 'Save' is performed. Note: By default, the created fillable template will be saved in 'zfdoc' format. The below key values are optional; http_method_type -> Specify the http method in which the save request has to be triggered. retries -> Specify the number of retries required when the 'Save' fails. timeout -> Specify the timeout for the given saveurl. save_url_params -> To customize the output parameters in which the document details will be pushed from our end.
document_defaults	{ "orientation":"portrait", "paper_size":"Letter", "font_name":"Lato", "font_size":14, "track_changes": "disabled", "margin": {"left":"1.5in","right":"1.5in","top":"0.25in","bottom":"0.25in"}, "date_format":"MM/DD/YY" }	Optional	Set document defaults such as font name/size, paper size, orientation, enable/disable track changes, custom margins, and date format.
editor_settings	{ "unit":"in", "language":"en", "view":"webview" }	Optional	Set editor preferences like unit (in/mm), interface language, and view mode (pageview/webview) for new documents.
permissions	{ "document.export":true, "document.print":true, "document.edit":true, "review.changes.resolve":false, "review.comment":true, "collab.chat":true, "document.pausecollaboration":false, "document.fill":true }	Optional	Define document permissions for the users.
document_info	{ "document_name":"New", "document_id":"1349" }	Optional	Set a unique document ID and specify the display name of the new document.
user_info	{ "user_id":"9173", "display_name":"Ken" }	Optional	Identify the user in the document with a user ID and display name.
ui_options	{ "save_button":"show", "chat_panel":"show" }	Optional	Specify whether the Save button and Chat panel are shown or hidden.

callback_settings

Parameter/Keys	Type	Mandatory/Optional	Possible Values	Default Value
save_url	String	Mandatory	URL (max length: 65535)	—
save_url_params	JSON	Optional	Max 10 keys. Allowed characters for <additional_user_key> - Alphabets, Numbers, Hyphen, Underscore and Dot. Maximum Length - 100 characters Maximum length of <value> - 2500 characters	—
http_method_type	String	Optional	post / put	post
retries	Integer	Optional	0 to 3	0
timeout	Integer	Optional	1 to 120000 (ms)	120000

save_url Usage

Zoho Office Integrator allows partners and businesses to save the document content back to their specified storage server through the save_url method.

A save_url is a publicly accessible web URL/Service to which Zoho will push the updated document content from Writer editor to the partner's server.

Requirements:

Partner's remote servers need to expose one of their ports — port 443 (HTTPS) or port 80 (HTTP) — for Zoho Writer to push the data back.
The save_url value specified in the request should be a proper domain name and publicly accessible over the web. Example: https://yourdomain.com/save.php

save_url_params Usage

By default, when 'Save' is performed, the following key names are pushed back:

Key Name	Type	Description
content	File	Document content will be pushed back in the form of bytes.
filename	String	Document name
format	String	Specifies the format in which the document has been exported.

To customize the above key names, use the save_url_params key inside the callback_settings parameter. Once configured, only the key values defined inside will be pushed back to your server. The default key names (like filename and format) will not be included unless you define your own keys using the system variables $format and $filename.

Syntax:

"save_url_params": {
      <custom_content_key>: $content,
      <custom_format_key>: $format,
      <custom_filename_key>: $filename,
      <additional_user_key>: <value>,
      <additional_user_key>: <value>,
      ....
      <additional_user_key>: <value>
      },

Example:

"save_url_params": {
      file: $content,
      extension: $format,
      document_name: $filename,
      <additional_user_key>: <value>,
      <additional_user_key>: <value>
      },

In the above example, the document bytes will be pushed back in the multipart name file, document format in the key name extension, and document filename in the key name document_name.

If save_url_params is passed as an empty JSON or the system variable $content is not configured, the document bytes will be pushed back with the multipart name content by default.

document_defaults

Parameter/Keys	Type	Mandatory/Optional	Possible Values	Default Value
font_name	String	Optional	e.g., Trebuchet	Arial
font_size	Integer	Optional	9 / 10 / 11 / 13 / 16 / 18 (px)	12 (px)
orientation	String	Optional	portrait / landscape	portrait
paper_size	String	Optional	Letter / A4 / Legal / Executive	Letter
track_changes	String	Optional	enabled / disabled	disabled
margin	JSON	Optional	in / mm (e.g., {"left":"1.5in","right":"1.5in","top":"0.25in","bottom":"0.25in"})	1in
date_format	String	Optional	e.g., EEEE, MMMM DD, YYYY at HH:mm	Based on document language

editor_settings

Parameter/Keys	Type	Mandatory/Optional	Possible Values	Default Value
unit	String	Optional	in / mm	in
language	String	Optional	en / de / es / fr / ja / nl and more	en
view	String	Optional	webview / pageview	pageview

permissions

Parameter/Keys	Type	Mandatory/Optional	Possible Values	Default Value
document.export	Boolean	Optional	true / false	true
document.print	Boolean	Optional	true / false	true
document.edit	Boolean	Optional	true / false	false
review.comment	Boolean	Optional	true / false	false
review.changes.resolve	Boolean	Optional	true / false	false
collab.chat	Boolean	Optional	true / false	true
document.pausecollaboration	Boolean	Optional	true / false	false
document.fill	Boolean	Optional	true / false	true

document_info

Parameter/Keys	Type	Mandatory/Optional	Possible Values	Default Value
document_id	String	Optional	e.g., 24eru24960v	—
document_name	String	Optional	e.g., Sample	Untitled

user_info

Parameter/Keys	Type	Mandatory/Optional	Possible Values	Default Value
user_id	String	Optional	e.g., 03588563264	—
display_name	String	Optional	e.g., Ken / James / Adam	Guest

ui_options

Parameter/Keys	Type	Mandatory/Optional	Possible Values	Default Value
save_button	String	Optional	show / hide	show
chat_panel	String	Optional	show / hide	show

Notes and Limits

Editor customization parameters and their values are case-sensitive.
Custom margin is applicable to new documents only.
The view parameter under editor_settings is applicable only for new documents.
By default, the created fillable template will be saved in 'zfdoc' format.
For possible error codes, refer to: Error Codes
For other server-side SDK sample code, refer to: Server-Side SDKs

Sample Request

Copiedcurl -X POST \
  https://writer.zoho.com/writer/officeapi/v1/fillabletemplates \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F apikey=423s***** \
  -F  document=@/Users/username/Documents/Sample.docx \
  -F 'editor_settings={'\''unit'\'':'\''in'\'','\''language'\'':'\''en'\'','\''view'\'':'\''webview'\''}' \
  -F 'permissions={'\''document.export'\'':true,'\''document.print'\'':true,'\''document.edit'\'':true,'\''review.changes.resolve'\'':false,'\''review.comment'\'':true,'\''collab.chat'\'':true,'\''document.pausecollaboration'\'':false,'\''document.fill'\'':true }' \
  -F 'callback_settings={'\''save_url'\'':'\''https://domain.com/save.php/'\'}' \
  -F 'document_info={'\''document_name'\'':'\''New'\'', '\''document_id'\'':1349}' \
  -F 'user_info={'\''user_id'\'':'\''1973'\'','\''display_name'\'':'\''Ken'\''}' \
  -F 'ui_options={"save_button":"show","chat_panel":"show"}'

Sample Response

Copied{ 
"document_url": "https://writer.zoho.com/writer/officeapi/v1/fillabletemplates/d26aa7b8029bf4f8d34c7dd0013939234a6e15dac88646f02a69582375b8da130efffac249d0erouae4667dcbcfb7ac1d/edit,
"document_id": "1349", 
"save_url": "https://writer.zoho.com/writer/officeapi/v1/fillabletemplates/d26aa7b8029bf4f8d34c7dd0013939234a6e15dac88646f02a69582375b8da130efffac249d086aae4667dcbcfb7ac1d/save", 
"session_id": "axxrd26aa7b8029bf4f8d34c7dd0013939234a6e15dac88646f02a69582375b8da130efffac249d086aae4667dcbac9p", 
"session_delete_url": "https://writer.zoho.com/writer/officeapi/v1/session/d26aa7b8029bf4f8d34c7dd0013939234a6e15dac88646f02a69582375b8da130efffac249d086aae4667dcbcfb7ac1d", 
"document_delete_url": "https://writer.zoho.com/writer/officeapi/v1/fillabletemplates/1349",
 }