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 https://documentserver/ConvertService.ashx address where the documentserver is the name of the server with the ONLYOFFICE Document Server installed.

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 response 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	Defines 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
password	Specifies the password for the document file if it is protected with a password.	string	optional
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 absolute URL 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
	bmp	docx	gif	jpg	odt	pdf	png	rtf	txt
doc
docm
docx
dot
dotm
dotx
epub
fodt
html
mht
odt
ott
pdf
rtf
txt
xps

Spreadsheet file formats

Input format	Output format
	bmp	csv	gif	jpg	ods	pdf	png	xlsx
csv
fods
ods
ots
xls
xlsm
xlsx
xlt
xltm
xltx

Presentation file formats

Input format	Output format
	bmp	gif	jpg	odp	pdf	png	pptx
fodp
odp
otp
pot
potm
potx
pps
ppsm
ppsx
ppt
pptm
pptx

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

Where the example.com is the name of 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.

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

Where the example.com is the name of 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.

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

Where the example.com is the name of 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.

The request result is returned in XML format. To receive a response in JSON format you need to specify in the HTTP request Header accept with the value application/json (available from version 4.3). When forming the link to the resulting file, the same server name is used which was made the conversion request to.

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

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

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

{
    "endConvert": true,
    "fileUrl": "https://documentserver/ResourceService.ashx?filename=output.doc",
    "percent": 100
}

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

{
    "endConvert": false,
    "percent": 95
}

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

{
    "error": -3
}

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