Content Conversion

The Content Conversion API allows you to convert files from a variety of input formats to several common output formats.

To convert a file:

1. Upload a file you want to use as input using the WorkFile API.
2. Start a conversion operation by using the POST URL below.
3. Check the status of the conversion by (repeatedly) using the GET URL below.
4. When complete, a separate output file will exist which you can download via the WorkFile API.

Available URLs

Note that these URLs begin with /v2, not /PCCIS/V1.

POST /v2/contentConverters

Creates a new contentConverter resource which represents the conversion process and begins converting one or multiple input files which you have previously uploaded using the WorkFile API. A successful response will include a unique processId which identifies this contentConverter. You will use this processId in subsequent GET calls to get the status and final results of the conversion.

Request Headers

Request Body

At a high level, your request body should be JSON containing an input object with details about the sources and dest for the conversion.

Here is a minimal example:

POST http://localhost:18681/v2/contentConverters
Content-Type application/json
{
    "input": {
        "sources": [
            { 
                "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
            }
        ],
        "dest": {
            "format": "pdf"
        }
    }
}

Additional options are available. Here is the full reference:

input.sources

The input.sources object specifies an array of objects, one for each input file.

Currently multiple input files are only supported when the destination format is pdf or tiff, but a future version of the product may allow you to submit multiple input source files for other destination formats.

input.src (deprecated)

The input.src object specifies the file to use as input. This property has been deprecated, please use input.sources instead.

input.dest

The input.dest object specifies the destination file format and any additional details which control how the content is converted.

input.dest.jpegOptions

For CAD input, you must specify either maxWidth or maxHeight.

input.dest.pdfOptions

When converting PDF documents to a single PDF with multiple pages or a set of single-page PDF files, the result PDF file(s) will lose bookmarks and intra-document links due to restructuring of the PDF content.

input.dest.pngOptions

For CAD input, you must specify either maxWidth or maxHeight.

input.dest.tiffOptions

For CAD input, you must specify either maxWidth or maxHeight.

input.dest.header

Currently, the input.dest.header property is only supported when converting all pages of a single document to either "pdf" or "tiff", and forceOneFilePerPage is false.

Text may overlap other text and/or overflow the page bounds. The caller specifies the text position and size, and the product simply renders the text. For example, if the font size is too big, text on the left may overlap text in the center, or if the text is so long it can't fit on the page width, it may overflow the page bounds.

For input.dest.header code examples refer to Conversion Input Examples.

input.dest.footer

Currently, the input.dest.footer property is only supported when converting all pages of a single document to either "pdf" or "tiff", and forceOneFilePerPage is false.

Text may overlap other text and/or overflow the page bounds. The caller specifies the text position and size, and the product simply renders the text. For example, if the font size is too big, text on the left may overlap text in the center, or if the text is so long it can't fit on the page width, it may overflow the page bounds.

For input.dest.footer code examples refer to Conversion Input Examples.

minSecondsAvailable

Allows you to specify a minimum number of seconds in which you can continue to GET the status of this conversion operation after the initial POST has been submitted. The default value is 60, ensuring that you have at least 60 seconds to get the result status of any conversion operation.

Response Body

A successful response will return JSON which contains:

1. The input object submitted in the request, normalized to include default values.
2. Information about the status of the conversion.

Here is an example:

200 OK
Content-Type: application/json
{
    "input": {
        "sources": [
            { 
                "fileId": "ek5Zb123oYHSUEVx1bUrVQ",
                "pages": ""
            }
        ],
        "dest": {
            "format": "pdf",
            "pdfOptions": {
                "forceOneFilePerPage": false
            }
        }
    },
    "expirationDateTime": "2015-12-17T20:38:39.796Z",
    "processId": "ElkNzWtrUJp4rXI5YnLUgw",
    "state": "processing",
    "percentComplete": 0
}

Conversion Status Details

HTTP Status Codes and Response JSON Error Codes

GET /v2/contentConverters/{processId}

Gets the status of a content conversion operation and its final output if available.

In general, the response JSON will contain:

1. The input object submitted in the POST request, normalized to include default values.
2. Information about the status of the conversion.
3. Information about the output of the conversion, if available.

Requests can be sent to this URL repeatedly while the state is "processing".

When the state is "complete", the output section will list one or more WorkFile ids for each output file, and the files themselves can be downloaded using the WorkFile API.

Parameters

Request Headers

Response Body

While processing, the response will return JSON with only the processing details. For example:

200 OK
Content-Type: application/json
{
    "input": {
        "sources": [
            { 
                "fileId": "ek5Zb123oYHSUEVx1bUrVQ",
                "pages": ""
            }
        ],
        "dest": {
            "format": "pdf",
            "pdfOptions": {
                "forceOneFilePerPage": false
            }
        }
    },
    "expirationDateTime": "2015-12-17T20:38:39.796Z",
    "processId": "ElkNzWtrUJp4rXI5YnLUgw",
    "state": "processing",
    "percentComplete": 82
}

Once the processing has completed, the response will return JSON showing the WorkFile id of the output file or files.

If the output format supports multiple pages (e.g. PDF or TIFF), then only a single output file will be created. For example:

200 OK
Content-Type: application/json
{
    "input": {
        "sources": [
            { 
                "fileId": "ek5Zb123oYHSUEVx1bUrVQ",
                "pages": ""
            }
        ],
        "dest": {
            "format": "pdf",
            "pdfOptions": {
                "forceOneFilePerPage": false
            }
        }
    },
    "expirationDateTime": "2015-12-17T20:38:39.796Z",
    "processId": "ElkNzWtrUJp4rXI5YnLUgw",
    "state": "complete",
    "percentComplete": 100,
    "output": {
        "results": [
            {
                "fileId": "KOrSwaqsguevJ97BdmUbXi",
                "sources": [{ "fileId": "ek5Zb123oYHSUEVx1bUrVQ", "pages": "1-3" }]
            }
        ]
    }
}

If the output format does not support multiple pages (e.g. JPEG), then multiple output files will be created. For example:

200 OK
Content-Type: application/json
{
    "input": {
        "sources": [
            { 
                "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
            }
        ],
        "dest": {
            "format": "jpeg"
        }
    },
    "expirationDateTime": "2015-12-17T20:38:39.796Z",
    "processId": "ElkNzWtrUJp4rXI5YnLUgw",
    "state": "complete",
    "percentComplete": 100,
    "output": {
        "results": [
            {
                "fileId": "N6uDE11Ed6+JQPy0POu+8A",
                "sources": [{ "fileId": "ek5Zb123oYHSUEVx1bUrVQ", "pages": "1" }]
            },
            {
                "fileId": "+4b6QW90Fb9yjDak+ALFEg",
                "sources": [{ "fileId": "ek5Zb123oYHSUEVx1bUrVQ", "pages": "2" }]
            },
            {
                "fileId": "Lx/4z8AyJKV5eMjWKsBm5w",
                "sources": [{ "fileId": "ek5Zb123oYHSUEVx1bUrVQ", "pages": "3" }]
            }
        ]
    }
}

Conversion Status Details

Conversion Output Details

HTTP Status Codes and Response JSON Error Codes

Appendix

Supported Input File Formats

For a complete list of image and document source types supported by CCS, please refer to: File Formats Reference.

Supported Output File Formats

• PDF
• TIFF
• PNG
• JPEG
• SVG