TRY NEW VERSION
Get Started
Usage API
Using WOPI
Additional API
More information

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 documentserver is the name of the server with the ONLYOFFICE Docs installed.

Starting from version 8.1, it is recommended to add the shardkey parameter to the URL QueryString with the key value in it. For example, ?shardkey=Khirz6zTPdfd7. This allows you to load balance requests.

In ONLYOFFICE Docs prior to version 4.2 the GET request with the parameters in the QueryString were used.
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
If the conversion is synchronous and the file takes a long time to be converted, a web request timeout error may occur. Although the conversion can be eventually completed, the result can only be obtained by sending the request again with the same key.
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 document layout which specifies parameters for printing forms as pdf documents or images. object optional
Defines if placeholders will be drawn or not. boolean optional
Defines if forms will be highlighted or not. boolean optional
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
Defines the document renderer when converting from pdf, xps, oxps. object optional
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
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. 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 converted 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 converted 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
Defines the password for the document file if it is protected with a password. string optional
Defines settings for converting document files to pdf. object optional
Defines whether the document will be converted to the pdf form (true) or to a regular pdf file (false). If this parameter is omitted, the document contents will not be changed. If the document has fields, they will remain in the converted document. If has not, the converted document will not contain them either. For example, you don't need to specify this parameter when converting docxf and oform formats to pdf. They will always be converted to pdf forms. boolean 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
Please note that the maximum number of pages that can be returned at once after converting a spreadsheet into pdf or image formats is no more than 1500.
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 ONLYOFFICE Docs config in the form of a token. string required by configuration
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
Defines a JSON object containing the properties of a watermark which is inserted into the pdf and image files during conversion. object optional
Defines the watermark transparency degree. float optional
Defines the shape type which specifies the preset shape geometry for the current watermark. string optional
Defines the watermark width measured in millimeters. number optional
Defines the watermark height measured in millimeters. number optional
Defines the watermark rotation angle measured in degrees. number optional
Defines the text margins measured in millimeters in the watermark shape. array of numbers optional
Defines the watermark fill color in the RGB format, or the URL to image (base64 support: data:image/png;...). The empty array [] means that the watermark has no fill. array of numbers | string optional
Defines the watermark stroke width measured in millimeters. number optional
Defines the watermark stroke color in the RGB format. The empty array [] means that the watermark stroke has no fill. array of numbers optional
Defines the vertical text align in the watermark shape: 0 - bottom, 1 - center, 4 - top. number optional
Defines the array with paragraphs from the current watermark with their properties. array of objects optional
Defines the horizontal text align in the current paragraph: 0 - right, 1 - left, 2 - center, 3 - justify. number optional
Defines the paragraph highlight in the RGB format. The empty array [] means that the paragraph is not highlighted. array of numbers optional
Defines the text linespacing in the current paragraph. number optional
Defines the array with runs from the current paragraph with their properties. array of objects optional
watermark.paragraphs.runs.text Defines the run text. string optional
Defines the text highlight in the RGB format. The empty array [] means that the text is not highlighted. array of numbers optional
Defines the text font family. string optional
Defines the text font size measured in points (pt). string optional
Defines if the current text is displayed bold or not. boolean optional
Defines if the current text is displayed italic or not. boolean optional
Defines if the current text is displayed struck through or not. boolean optional
Defines if the current text is displayed underlined or not. boolean optional
* - 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 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
htm
html
mht
mhtml
odt
ott
oxps
pdf
rtf
stw
sxw
txt
wps
wpt
xml
xps
Input format Output format
bmp csv gif jpg ods ots pdf pdfa png xlsm xlsx xltm xltx
csv
et
ett
fods
ods
ots
sxc
xls
xlsb
xlsm
xlsx
xlt
xltm
xltx
xml
Input format Output format
bmp gif jpg odp otp pdf pdfa png potm potx ppsm ppsx pptm pptx
dps
dpt
fodp
odp
otp
pot
potm
potx
pps
ppsm
ppsx
ppt
pptm
pptx
sxi 
{
    "async": false,
    "filetype": "docx",
    "key": "Khirz6zTPdfd7",
    "outputtype": "pdf",
    "title": "Example Document Title.docx",
    "url": "https://example.com/url-to-example-document.docx"
}

Where 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 ONLYOFFICE Docs 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 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 ONLYOFFICE Docs service client-server interactions. 

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

Where 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 ONLYOFFICE Docs service client-server interactions. 

{
    "async": false,
    "filetype": "docx",
    "key": "Khirz6zTPdfd7",
    "outputtype": "pdf",
    "title": "Example Document Title.docx",
    "url": "https://example.com/url-to-example-document.docx",
    "watermark": {
        "align": 1,
        "fill": [255, 0, 0],
        "height": 100,
        "margins": [ 10, 10, 10, 10 ],
        "paragraphs": [
            {
                "align": 2,
                "fill": [255, 0, 0],
                "linespacing": 1,
                "runs": [
                    {
                        "bold": true,
                        "italic": false,
                        "fill": [0, 0, 0],
                        "font-family": "Arial",
                        "font-size": 40,
                        "strikeout": false,
                        "text": "Watermark",
                        "underline": false
                    },
                    {
                        "text": "<%br%>"
                    }
                ]
            }
        ],
        "rotate": -45,
        "transparent": 0.3,
        "type": "rect",
        "stroke-width": 1,
        "stroke": [0, 0, 255],
        "width": 100
    }
}

Where 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 ONLYOFFICE Docs 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 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 ONLYOFFICE Docs 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 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 ONLYOFFICE Docs service client-server interactions. 

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

Where 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 ONLYOFFICE Docs service client-server interactions.

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
Defines if the conversion is completed or not. boolean true
Defines an error occurred during the conversion. Possible error codes can be found here. integer -3
Defines an extension of the converted file. string "docm"
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"
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
}
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.
-9 Error when the converter cannot automatically determine the output file format. This error means that the client must explicitly specify in which format the file should be converted (text document or spreadsheet). It is used to convert XML to OOXML in case the XML type is unknown.
-10 Size limit exceeded.
Get information
Get help
onlyoffice.com
© Ascensio System SIA 2024. All rights reserved