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.

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 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. The default value is false.
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
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
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 password for the document file if it is protected with a password. string optional
Defines the default display format for currency and date and time when converting from Spreadsheet format to pdf. Is set using the four letter (en-US, fr-FR, etc.) language codes. The default value is en-US. string optional
Defines settings for converting the spreadsheet to pdf. object optional
Sets the height of the converted area, measured in the number of pages. The default value is 0. integer optional
Sets the width of the converted area, measured in the number of pages. The default value is 0. integer optional
Allows to include grid lines to the output PDF file or not. The default value is false. boolean optional
Allows to include the headings to the output PDF file or not. The default value is false. boolean optional
Determines whether to ignore the print area chosen for the spreadsheet file or not. The default value is true. boolean optional
Sets the margins of the output PDF file. object optional
Sets the bottom margin of the output PDF file. The default value is 19.1mm. string optional
Sets the left margin of the output PDF file. The default value is 17.8mm. string optional
Sets the right margin of the output PDF file. The default value is 17.8mm. string optional
Sets the top margin of the output PDF file. The default value is 19.1mm. string optional
Sets the orientation of the output PDF file. May be landscape, portrait. The default value is portrait. string optional
Sets the page size of the output PDF file. object optional
Sets the page height of the output PDF file. The default value is 297mm. string optional
Sets the page width of the output PDF file. The default value is 210mm. string optional
Allows to set the scale of the output PDF file. The default value is 100. integer optional
Defines the settings for the thumbnail when specifying the image formats (bmp, gif, jpg, png) as outputtype. object optional
Defines 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,
  • 2 - in this case, the width and height settings are not used. Instead of that, metric sizes of the page are converted into pixels with 96dpi. E.g., the A4 (210x297mm)┬ápage will turn out to be a picture with the 794x1123pix dimensions.
The default value is 2.
integer optional
Defines 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, boolean optional
Defines the thumbnail height in pixels. The default value is 100. integer optional
Defines the thumbnail width in pixels. The default value is 100. integer optional
Defines the converted file name. string optional
Defines the encrypted signature added to the Document Server config in the form of a token. string required by configuration
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.
Input format Output format
bmp docx gif jpg odt pdf pdfa png rtf txt
doc
docm
docx
dot
dotm
dotx
epub
fodt
html
mht
odt
ott
pdf
rtf
txt
xps
Input format Output format
bmp csv gif jpg ods pdf pdfa png xlsx
csv
fods
ods
ots
xls
xlsm
xlsx
xlt
xltm
xltx
Input format Output format
bmp gif jpg odp pdf pdfa 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.

{
    "filetype": "xlsx",
    "key": "Khirz6zTPdfd7",
    "outputtype": "pdf",
    "region": "en-US",
    "spreadsheetLayout": {
        "ignorePrintArea": true,
        "orientation": "portrait",
        "fitToWidth": 0,
        "fitToHeight": 0,
        "scale": 100,
        "headings": false,
        "gridLines": false,
        "pageSize": {
            "width": "210mm",
            "height": "297mm"
        },
        "margins": {
            "left": "17.8mm",
            "right": "17.8mm",
            "top": "19.1mm",
            "bottom": "19.1mm"
        }
    },
    "title": "Example Document Title.docx",
    "url": "https://example.com/url-to-example-spreadsheet.xlsx"
}

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.

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaWxldHlwZSI6ImRvY3giLCJrZXkiOiJLaGlyejZ6VFBkZmQ3Iiwib3V0cHV0dHlwZSI6InBkZiIsInRpdGxlIjoiRXhhbXBsZSBEb2N1bWVudCBUaXRsZS5kb2N4IiwidXJsIjoiaHR0cDovL2V4YW1wbGUuY29tL3VybC10by1leGFtcGxlLWRvY3VtZW50LmRvY3gifQ.U-YAfuuy7clWjn-xOncfJ-sxVG5DlcYn0AOzJYkoR0M"
}

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.

Sample of the response in XML format

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>
Sample of the response in JSON format

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
}
Sample of the intermediate response to the asynchronous request (with the parameter async=true) in XML format
<?xml version="1.0" encoding="utf-8"?>
<FileResult>
    <EndConvert>False</EndConvert>
    <FileUrl></FileUrl>
    <Percent>95</Percent>
</FileResult>
Sample of the intermediate response to the asynchronous request (with the parameter async=true) in JSON format
{
    "endConvert": false,
    "percent": 95
}
Sample of the response when an error occurred in XML format
<?xml version="1.0" encoding="utf-8"?>
<FileResult>
    <Error>-3</Error>
</FileResult>
Sample of the response when an error occurred in JSON format
{
    "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.
-7 Input error.
-8 Invalid token.