Converter API documentation

Every conversion request call must be authenticated with secret or token and submited as query parameter. More detailed authentication methods covered in Authentication web page. All supported file format conversions are provided here.


Request


application/json

JSON scheme also can be built in Code Snippets section. File data must be encoded with Base64 encoding, provided as URL or uploaded File ID.

DOC to PDF scheme example:
POST https://v2.convertapi.com/doc/to/pdf?Secret=XXX
{
    "Parameters": [
        {
            "Name": "File",
            "FileValue": {
                "Name": "my_file.doc",
                "Data": "--Base64 encoded file content--"
            }
        }
    ]
}
Merge PDF scheme example (multiple source files):
POST https://v2.convertapi.com/pdf/to/merge?Secret=XXX
{
    "Parameters": [
        {
            "Name": "StoreFile",
            "Value": "true"
        },
        {
            "Name": "PdfVersion",
            "Value": "1.7"
        },
        {
            "Name": "Files",
            "FileValues": [
                {
                    "Name": "file.pdf",
                    "Data": "--Base64 encoded file content--"
                },
                {
                    "Url": "http://example.com/myfile.docx"
                },
                {
                    "Id": "13232131"
                }
            ]
        }
    ]
}

multipart/form-data

Each request parameter must be in separate part. If there is an array type parameter, index must be appended to parameter name e.g. Files[0], Files[1], Files[2] etc.

DOC to PDF example:
POST /doc/to/pdf?secret=XXXX HTTP/1.1
Host: v2.convertapi.com
Cache-Control: no-cache
Content-Type: multipart/form-data; boundary=----7MA4YWxkTrZu0gW

------7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="StoreFile"

true
------7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="File"; filename="my_file.doc"
Content-Type: 

--FILE DATA--
------7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="DocumentTitle"

Test title
------7MA4YWxkTrZu0gW--

application/octet-stream

Most bandwidth efficient way to convert file is to pass file content as a request body. Also this content type could be used for stream processing. Request header must contain field: Content-Disposition: attachment; filename="my_file.doc" with the file name and correct file extension. Conversion parameters can be set throw URL query.

Query parameters

Using query parameters it is possible to convert file which is accessible by URL or uploaded File ID.

DOCX to PDF URL example:
https://v2.convertapi.com/docx/to/pdf?Secret=XXX&File=http://example.com/myfile.docx&StoreFile=true
If there is an array type parameter, index must be appended to parameter name e.g. Files[0], Files[1], Files[2] etc.

Response


Response headers and body contains this information:

  • ConversionTime - time in seconds that took to convert file. In this amount of seconds your balance will be decreased after conversion.
  • FileName - name of converted file.
  • FileSize - converted file size in bytes.
  • FileData - converted file content.
  • FileUrl - link to converted file if "StoreFile" parameter is set to "true".

application/json

Response scheme can be explored in Test Request response box.

Single file result example:
{
    "ConversionTime": 2,
    "Files": [
        {
            "FileName": "my_file.pdf",
            "FileSize": 523672,
            "FileData": "--Base64 encoded file content--"
        }
    ]
}

application/xml

XML scheme is analogous to JSON.

Single file result example:
<Conversion xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ConversionTime>2</ConversionTime>
<Files>
    <File>
        <FileName>my_file.pdf</FileName>
        <FileSize>522579</FileSize>
        <FileData>--Base64 encoded file content--</FileData>
        <Url i:nil="true" />
    </File>
</Files>
</Conversion>

multipart/mixed

each part contains converted file data or URL to the file.

Single file result example:
--43cf1475-ab15-4c6b-b5ee-e2cbcedfe92f
ConversionTime: 3
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="my_file.pdf"; size=8475

--FILE CONTENT--
                
--43cf1475-ab15-4c6b-b5ee-e2cbcedfe92f--

application/octet-stream

Response body is result file content. File name can be found in content-disposition header field. Can be used with converters that produce only one file result.


HTTP Response Codes


200

Conversion completed successfully.

401

Internal codes provided in response body:

  • 4010 - Invalid user credentials - bad secret.
  • 4011 - Invalid user credentials - bad token.
  • 4012 - Invalid user credentials - bad self generated token.
  • 4013 - User credentials not set, secret or token must be passed.
  • 4014 - User inactive.

404

Internal codes provided in response body:

  • 4040 - Parameter validation error.
  • 4041 - No content disposition provided.

500

Internal codes provided in response body:

  • 5000 - Conversion timeout.
  • 5001 - Conversion failed.
  • 5002 - PDF file is damaged.
  • 5003 - File has copy protection.
  • 5004 - No tables to extract in PDF file.
  • 5005 - Invalid URL format.
  • 5006 - Invalid password.
  • 5007 - Unable to download remote file.
  • 5008 - Unable to access file from local storage.
  • 5009 - File id is invalid.
  • 50010 - File link is set incorrectly. Url or File Id must be set.
  • 50011 - Can't delete.

502

Internal codes provided in response body:

  • 5020 - Worker maximum parallel jobs reached.

Other features


Conversion chaining

Converted files that are stored on convertapi.com server can be accessible for further conversion operations. This method allows conversion chaining, without increased network load. Example: conversion PDF to JPG produces as many files as there are pages in PDF file. If these files are stored on the server and links to the files are passed to ZIP converter, result will be one ZIP file with JPG files of each PDF page.


View file in browser

If ?view=true is appended to a stored conversion result file download link, file will be viewed in browser rather than downloaded.

Example:
https://v2.convertapi.com/d/HQ5TRU5Z/my_file.pdf?view=true

Asynchronous file conversions

Asynchronous file conversions are made by setting parameter Async to "true". Response of the asynchronous conversion will be returned right after the request.

Asynchronous conversion request example:
POST https://v2.convertapi.com/docx/to/pdf?Secret=XXX&Async=true&File=http://example.com/myfile.docx
Asynchronous conversion response example:
{
    "JobId": "d3bd2056-4330-4cf3-9b18-483a2412dd6b"
}

With the JobId it is possible to retrieve finished conversion result or get the conversion status.

Example:
GET https://v2.convertapi.com/job/d3bd2056-4330-4cf3-9b18-483a2412dd6b/result
Response HTTP status codes:
  • 200 - conversion is successful. Response is a conversion result.
  • 202 - conversion is processing.
  • 404 - JobId is invalid or response is expired.
  • 5XX - conversion error. Response is an error message.

Semi-Asynchronous file conversions

Semi-Asynchronous file conversions are useful when connection to ConvertAPI is lost during large file conversion. To avoid repetitive conversion, provide JobId parameter with self generated UUID (RFC 4122).

Semi-Asynchronous conversion request example:
POST https://v2.convertapi.com/docx/to/pdf?Secret=XXX&JobId=d3bd2056-4330-4cf3-9b18-483a2412dd6b&File=http://example.com/myfile.docx

In case of disrupted connection treat this conversion as if it was asynchronous conversion. Retrieve conversion result like described in asynchronous conversion section.

GET method conversions

Convertapi.com can be used as a virtual file server for all your files or web pages that needs to be converted. File is getting converted on demand, when user clicks on the link. Result can be displayed in a web browser or downloaded. Set query parameter view=true to display conversion result in a browser instead of downloading.

Example:
<a href="https://v2.convertapi.com/web/to/pdf?token=XXX&view=true&url=http://example.com/">View page as PDF</a>
<a href="https://v2.convertapi.com/web/to/pdf?token=XXX&url=http://example.com/">Save page as PDF</a>
<a href="https://v2.convertapi.com/docx/to/pdf?token=XXX&file=https://example.com/my_file.docx">Save DOCX as PDF</a>