Conversion API

Purpose

Convert a document to any Writer supported format (.docx, .doc, .pdf, .zdoc etc.). Zoho Writer's conversion API lets you easily integrate document conversion functionality into web applications and content management systems.

Quick Reference

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

Parameters

Body Parameters

Parameter	Value	Mandatory/Optional	Description
apikey	423s*****	Mandatory	Uniquely identifies the web application which initiates the document conversion request.
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.
output_options	{ "format": <String>, "document_name": <String>, "password": <String>, "include_changes": <String>, "include_comments": <String> }	Mandatory	format -> Specify the output format in which the converted file needs to be stored. document_name -> Specify the name for the converted document. The below key values are optional; password -> Specify a password if you would like to protect the converted document. include_changes -> Specify how the track changed content needs to be reflected in converted file. The possible values are: as_markups: If the marked up content needs to be included in converted document. all: To generate the converted file by accepting all the track changes done. none: To generate the converted document by rejecting the track changes done. include_comments -> Specify if the comments need to be included in the converted file or not. The possible values are: all: To generate the converted file with the comments. none: To generate the converted document without the comments.
password	String	Optional	If the input document is password protected, specify it using this parameter.

output_options

Parameter/Keys	Type	Mandatory/Optional	Possible Values	Default Value
format	String	Mandatory	docx / zdoc / doc / odt / html / pdf and more	docx
document_name	String	Mandatory	NA	NA
password	String	Optional	NA	NA
include_changes	String	Optional	as_markups / all / none	as_markups
include_comments	String	Optional	all / none	all

Notes and Limits

Users will get a response of the converted document in the form of bytes.
For possible error codes, refer to: Error Codes
For other server-side SDK sample code, refer to: Server-Side SDKs

Sample Request

Curl Node JS

Copiedcurl -X POST \ 
  'https://api.office-integrator.com/writer/officeapi/v1/document/convert?apikey=423s*****' \
  - H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  - F 'document=@/Users/username/Documents/Sample.docx' \
  - F 'output_options={"format":"docx","document_name":"New"}'

Copiedimport * as SDK from "@zoho-corp/office-integrator-sdk";
import { readFileSync, writeFileSync } from 'fs';
const __dirname = import.meta.dirname;

class ConvertDocument {

    static async execute() {
        
        //Initializing SDK once is enough. Calling here since code sample will be tested standalone. 
        //You can place SDK initializer code in you application and call once while your application start-up. 
        await this.initializeSdk();

        try {
            var sdkOperations = new SDK.V1.V1Operations();
            var documentConversionParameters = new SDK.V1.DocumentConversionParameters();

            //Either use url as document source or attach the document in request body use below methods
            documentConversionParameters.setUrl("https://demo.office-integrator.com/zdocs/MS_Word_Document_v0.docx");

            // var fileName = "Graphic-Design-Proposal.docx";
            // var filePath = __dirname + "/sample_documents/Graphic-Design-Proposal.docx";
            // var fileStream = readFileSync(filePath);
            // var streamWrapper = new SDK.StreamWrapper(fileName, fileStream, filePath);

            // documentConversionParameters.setDocument(streamWrapper);

            var outputOptions = new SDK.V1.DocumentConversionOutputOptions();

            outputOptions.setFormat("pdf");
            outputOptions.setDocumentName("conversion_output.pdf");
            outputOptions.setIncludeComments("all");
            outputOptions.setIncludeChanges("all");

            documentConversionParameters.setOutputOptions(outputOptions);
            documentConversionParameters.setPassword("***");

            var responseObject = await sdkOperations.convertDocument(documentConversionParameters);

            if(responseObject != null) {
                console.log("\nStatus Code: " + responseObject.statusCode);
    
                //Get the api response object from responseObject
                let writerResponseObject = responseObject.object;

                if(writerResponseObject != null) {
                    if(writerResponseObject instanceof SDK.V1.FileBodyWrapper) {
                        var convertedDocument = writerResponseObject.getFile();

                        if (convertedDocument instanceof SDK.StreamWrapper) {
                            var outputFilePath = __dirname + "/sample_documents/conversion_output.pdf";

                            writeFileSync(outputFilePath, convertedDocument.getStream());
                            console.log("\nCheck converted output file in file path - ", outputFilePath);
                        }
                    } else if (writerResponseObject instanceof SDK.V1.InvalidConfigurationException) {
                        console.log("\nInvalid configuration exception. Exception json - ", writerResponseObject);
                    } else {
                        console.log("\nRequest not completed successfullly");
                    }
                }
            }
        } catch (error) {
            console.log("\nException while running sample code", error);
        }
    }

    //Include office-integrator-sdk package in your package json and the execute this code.

    static async initializeSdk() {

        // Refer this help page for api end point domain details -  https://www.zoho.com/officeintegrator/api/v1/getting-started.html
        let environment = await new SDK.DataCenter.Production("https://api.office-integrator.com");

        let auth = new SDK.AuthBuilder()
                        .addParam("apikey", "2ae438cf864488657cc9754*****") //Update this apikey with your own apikey signed up in office integrator service
                        .authenticationSchema(await new SDK.V1.Authentication().getTokenFlow())
                        .build();

        let tokens = [ auth ];

        //Sdk application log configuration
        let logger = new SDK.LogBuilder()
            .level(SDK.Levels.INFO)
            //.filePath("<file absolute path where logs would be written>") //No I18N
            .build();

        let initialize = await new SDK.InitializeBuilder();

        await initialize.environment(environment).tokens(tokens).logger(logger).initialize();

        console.log("SDK initialized successfully.");
    }

}

ConvertDocument.execute();

Sample Response

The converted document will be downloaded as bytes.