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.

Request 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. The default value is false.	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
documentLayout	Defines the document layout which specifies parameters for printing forms as pdf documents or images.	object	optional
documentLayout.drawPlaceHolders	Defines if placeholders will be drawn or not.	boolean	optional
documentLayout.drawFormHighlight	Defines if forms will be highlighted or not.	boolean	optional
documentLayout.isPrint	Defines if the print mode is turned on or off. This parameter is used only for converting docx/docxf into pdf. If this parameter is equal to true, the drawPlaceHolders and drawFormHighlight flags are used as described above. If this parameter is false, the drawFormHighlight flag does not work and the drawPlaceHolders parameter allows saving the forms in the pdf format. The default value is false.	boolean	optional
documentRenderer	Defines the document renderer when converting from pdf, xps, oxps.	object	optional
documentRenderer.textAssociation	Defines the rendering mode that can have the following values: blockChar - all text is converted by single characters. Each character is in its own frame (like a textbox), blockLine - all text is converted by separate lines. Each text line is in its own frame. Lines can be combined within the same block, plainLine - all text is converted as a plain text. But each line is a separate paragraph, plainParagraph - all text is converted as a plain text. Lines are combined into paragraphs. The default value is plainLine.	string	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. Starting from version 7.0, file formats can be specified instead of extensions. They are used when we do not know in advance what extension is required: ooxml - defines that the file will be coverted into docx, docm, xlsx, xlsm, pptx or pptm. For example, when the doc file is converted into the OOXML format, the resulting file can be docx or docm if this file contains macros (the same for xls and ppt). It is also applied when converting XML files into OOXML formats (docx, xlsx or pptx depending on the content); odf - defines that the file will be coverted into odt, ods or odp. For example, it is used when converting XML files into ODF formats (odt, ods or odp depending on the content).	string	required
password	Defines the password for the document file if it is protected with a password.	string	optional
region	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
spreadsheetLayout	Defines settings for converting the spreadsheet to pdf.	object	optional
spreadsheetLayout.fitToHeight	Sets the height of the converted area, measured in the number of pages. The default value is 0.	integer	optional
spreadsheetLayout.fitToWidth	Sets the width of the converted area, measured in the number of pages. The default value is 0.	integer	optional
spreadsheetLayout.gridLines	Allows to include grid lines to the output PDF file or not. The default value is false.	boolean	optional
spreadsheetLayout.headings	Allows to include the headings to the output PDF file or not. The default value is false.	boolean	optional
spreadsheetLayout.ignorePrintArea	Determines whether to ignore the print area chosen for the spreadsheet file or not. The default value is true.	boolean	optional
spreadsheetLayout.margins	Sets the margins of the output PDF file.	object	optional
spreadsheetLayout.margins.bottom	Sets the bottom margin of the output PDF file. The default value is 19.1mm.	string	optional
spreadsheetLayout.margins.left	Sets the left margin of the output PDF file. The default value is 17.8mm.	string	optional
spreadsheetLayout.margins.right	Sets the right margin of the output PDF file. The default value is 17.8mm.	string	optional
spreadsheetLayout.margins.top	Sets the top margin of the output PDF file. The default value is 19.1mm.	string	optional
spreadsheetLayout.orientation	Sets the orientation of the output PDF file. May be landscape, portrait. The default value is portrait.	string	optional
spreadsheetLayout.pageSize	Sets the page size of the output PDF file.	object	optional
spreadsheetLayout.pageSize.height	Sets the page height of the output PDF file. The default value is 297mm.	string	optional
spreadsheetLayout.pageSize.width	Sets the page width of the output PDF file. The default value is 210mm.	string	optional
spreadsheetLayout.scale	Allows to set the scale of the output PDF file. The default value is 100.	integer	optional
thumbnail	Defines the settings for the thumbnail when specifying the image formats (bmp, gif, jpg, png) as outputtype.	object	optional
thumbnail.aspect	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
thumbnail.first	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
thumbnail.height	Defines the thumbnail height in pixels. The default value is 100.	integer	optional
thumbnail.width	Defines the thumbnail width in pixels. The default value is 100.	integer	optional
title	Defines the converted file name.	string	optional
token	Defines the encrypted signature added to the Document Server config in the form of a token.	string	required by configuration
url	Defines the absolute URL to the document to be converted. Be sure to add a token when using local links. Otherwise, an error will occur.	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	docm	docx	docxf	dotm	dotx	epub	fb2	gif	html	jpg	odt	ott	pdf	pdfa	png	rtf	txt
djvu
doc
docm
docx
docxf
dot
dotm
dotx
epub
fb2
fodt
html
mht
odt
ott
oxps
pdf
rtf
txt
xps
xml

Spreadsheet file formats

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

Presentation file formats

Input format	Output format
Input format	bmp	gif	jpg	odp	otp	pdf	pdfa	png	potm	potx	pptm	pptx
fodp
odp
otp
pot
potm
potx
pps
ppsm
ppsx
ppt
pptm
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": "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.

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

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

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": "https://example.com/url-to-example-document.docx"
}

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

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

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

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

Response parameters and their description

The request result is returned in XML format. To receive a response in JSON format you need to specify the Accept header with the application/json value in the HTTP request (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.

Parameter	Description	Type	Example
endConvert	Defines if the conversion is completed or not.	boolean	true
error	Defines an error occurred during the conversion. Possible error codes can be found here.	integer	-3
fileType	Defines an extension of the converted file.	string	"docm"
fileUrl	Defines the link to the converted document. This parameter will be received only when the endConvert parameter is set to true.	string	"https://documentserver/url-to-converted-document.pdf"
percent	Defines the percentage of the file conversion. If the endConvert parameter is set to true, the percent is equal to 100.	integer	100

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>
    <FileType>docm</FileType>
    <FileUrl>https://documentserver/url-to-converted-document.pdf</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,
    "fileType": "docm",
    "fileUrl": "https://documentserver/url-to-converted-document.pdf",
    "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>
    <FileType></FileType>
    <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
}

Possible error codes and their description

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.