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
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
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
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
Defines the type of the document file to be converted. string required
Defines the document identifier used to unambiguously identify the document file. string required
Defines the resulting converted document type. string required
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
Defines the converted file name. string optional
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.
Input format Output format
bmp docx gif jpg odt pdf png rtf txt
doc
docx
epub
html
mht
odt
pdf
rtf
txt
xps
Input format Output format
bmp csv gif jpg ods pdf png xlsx
csv
ods
xls
xlsx
Input format Output format
bmp gif jpg odp pdf png pptx
odp
pps
ppsx
ppt
pptx
{
    "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.

{
    "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"
}

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.

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.