Conversion API

For the interaction with the document conversion service the POST requests are used. The request parameters are entered in JSON format in the request body. The requests are sent to the http://documentserver/ConvertService.ashx address where the documentserver is the name of the server with the ONLYOFFICE Document Server installed.

In ONLYOFFICE Document Server prior to version 4.2 the GET request with the parameters in the QueryString were used.

Parameters and their description:

Parameter	Description	Type	Presence
async	Defines the conversion request type: asynchronous or not. Supported values: true false When the asynchronous request type is used, the reply is formed instantly. In this case to get the result it is necessary to send requests without parameter change until the conversion is finished.	boolean	optional
codePage	Defines the file encoding when converting from csv or txt format. Main supported values: 932 - Japanese (Shift-JIS), 950 - Chinese Traditional (Big5), 1250 - Central European (Windows), 1251 - Cyrillic (Windows), 65001 - Unicode (UTF-8). You can find all the supported values in this file.	integer	optional
delimiter	Dfines the delimiter characters for separating values when converting from csv format. Supported values: 0 - no delimiter, 1 - tab, 2 - semicolon, 3 - colon, 4 - comma, 5 - space.	integer	optional
filetype*	Defines the type of the document file to be converted.	string	required
key	Defines the document identifier used to unambiguously identify the document file.	string	required
outputtype*	Defines the resulting converted document type.	string	required
thumbnail	Defines the option is used since version 4.2. Settings for the thumbnail when specifying the image formats (bmp, gif, jpg, png) as outputtype. The object has the following parameters: aspect - sets the mode to fit the image to the height and width specifyed. Supported values: 0 - stretch file to fit height and width, 1 - keep the aspect for the image, type: integer, example: 1; first - specifies if the thumbnails should be generated for the first page only or for all the document pages. If false, the zip archive containing thumbnails for all the pages will be created. The default value is true, type: boolean, example: true; height - the thumbnail height in pixels (default: 100), type: integer, example: 100; width - the thumbnail width in pixels (default: 100), type: integer, example: 100.	object	optional
title	Defines the converted file name.	string	optional
url	Defines the link to the document to be converted.	string	required

* - in the tables below you can see possibility of conversion your documents into the most known file formats, where the Input format column corresponds to the values of the filetype parameter and the Output format columns correspond to the values of the outputtype parameter.

Text document file formats

Input format	Output format
Input format	bmp	docx	gif	jpg	odt	pdf	png	rtf	txt
doc	✓	✓	✓	✓	✓	✓	✓	✓	✓
docx	✓		✓	✓	✓	✓	✓	✓	✓
epub	✓	✓	✓	✓	✓	✓	✓	✓	✓
html	✓	✓	✓	✓	✓	✓	✓	✓	✓
mht	✓	✓	✓	✓	✓	✓	✓	✓	✓
odt	✓	✓	✓	✓		✓	✓	✓	✓
pdf	✓		✓	✓			✓
rtf	✓	✓	✓	✓	✓	✓	✓		✓
txt	✓	✓	✓	✓	✓	✓	✓	✓
xps	✓		✓	✓		✓	✓

Spreadsheet file formats

Input format	Output format
Input format	bmp	csv	gif	jpg	ods	pdf	png	xlsx
csv	✓		✓	✓	✓	✓	✓	✓
ods	✓	✓	✓	✓		✓	✓	✓
xls	✓	✓	✓	✓	✓	✓	✓	✓
xlsx	✓	✓	✓	✓	✓	✓	✓

Presentation file formats

Input format	Output format
Input format	bmp	gif	jpg	odp	pdf	png	pptx
odp	✓	✓	✓		✓	✓	✓
pps	✓	✓	✓	✓	✓	✓	✓
ppsx	✓	✓	✓	✓	✓	✓	✓
ppt	✓	✓	✓	✓	✓	✓	✓
pptx	✓	✓	✓	✓	✓	✓

Sample of JSON object sent to document conversion service used to convert the file from docx format to pdf format

{
    "async": false,
    "filetype": "docx",
    "key": "Khirz6zTPdfd7",
    "outputtype": "pdf",
    "title": "Example Document Title.docx",
    "url": "http://example.com/url-to-example-document.docx"
}

Where the example.com is the name of the the server where document manager and document storage service are installed. See the How it works section to find out more on Document Server service client-server interactions.

Sample of JSON object sent to document conversion service used to generate png thumbnail of file in docx format

{
    "filetype": "docx",
    "key": "Khirz6zTPdfd7",
    "outputtype": "png",
    "thumbnail": {
        "aspect": 0,
        "first": true,
        "height": 150,
        "width": 100
    },
    "title": "Example Document Title.docx",
    "url": "http://example.com/url-to-example-document.docx"
}

The request result is returned in XML form.

Reply format

<?xml version="1.0" encoding="utf-8"?>
<FileResult>
    <FileUrl>[Link to the converted file at the server]</FileUrl>
    <Percent>[Conversion progress percentage]</Percent>
    <EndConvert>[Conversion is finished - True|False]</EndConvert>
</FileResult>

When forming the link to the resulting file, the same server name is used which was made the conversion request to.

Reply example

<?xml version="1.0" encoding="utf-8"?>
<FileResult>
    <FileUrl>http://documentserver/ResourceService.ashx?filename=output.doc</FileUrl>
    <Percent>100</Percent>
    <EndConvert>True</EndConvert>
</FileResult>

Example of the intermediate reply to the asynchronous request (with the parameter async=true)

<?xml version="1.0" encoding="utf-8"?>
<FileResult>
    <FileUrl></FileUrl>
    <Percent>95</Percent>
    <EndConvert>False</EndConvert>
</FileResult>

Reply format when an error occurred

<?xml version="1.0" encoding="utf-8"?>
<FileResult>
    <Error>Error code</Error>
</FileResult>

Example of the reply when an error occurred

<?xml version="1.0" encoding="utf-8"?>
<FileResult>
    <Error>-3</Error>
</FileResult>

Possible error codes and their description

Error code	Description
-1	Unknown error.
-2	Timeout conversion error.
-3	Conversion error.
-4	Error while downloading the document file to be converted.
-6	Error while accessing the conversion result database.
-8	Invalid token.