Content types and schemes

In this documentation section are covered all content types and schemes that are supported by convertapi.com.

Conversion request content types and schemes

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 request example
Request:
POST https://v2.convertapi.com/convert/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)
Request:
POST https://v2.convertapi.com/convert/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
Request:
POST /convert/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
Request:
GET/POST https://v2.convertapi.com/convert/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.

Conversion response content types and schemes

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
Response:
{
    "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
Response:
<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
Response:
--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 is password protected.
  • 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.