Introduction

The content converters REST API allows your application to convert files from a variety of input formats to several common output formats.

For application development in .NET, we recommend using the PrizmDoc Server .NET SDK instead of the REST API. See the .NET SDK How to Guides for examples of how to perform file conversion with the .NET SDK.

To convert a file using the REST API:

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 prizmdoc_server_base_url/v2/contentConverters
Content-Type application/json

{
    "input": {
        "sources": [
            {
                "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
            }
        ],
        "dest": {
            "format": "pdf"
        }
    }
}

NOTE: See the Base URL for PrizmDoc Server topic for more information.

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.sources[n].wordOptions

The input.sources[n].wordOptions object will be considered only when the source is a supported Microsoft Word or OpenDocument Text format:

• doc
• docx
• docm
• dot
• dotx
• dotm
• odt
• ott
• fodt

Otherwise it will be ignored. The object has a trackedChanges enumeration property that controls how tracked changes should be handled in Microsoft Word documents (not supported for .odt, .ott, .fodt formats). Supported values:

• "preserve" - Preserve all tracked changes, neither accepting nor rejecting them before creating the output file. Output PDFs, images, or SVGs will visually show the tracked changes in a different color (additions as colored text and deletions as struck-through colored text).
• "acceptAll" - Accept all tracked changes before creating the output file(s).
• "rejectAll" - Reject all tracked changes before creating the output file(s).

The default is "preserve" (where output PDFs, images, and SVGs will visually show the tracked changes). If you want to create output files where tracked changes are not shown, specify one of the other options.

NOTE: In order to use "acceptAll" and "rejectAll" values, the Microsoft Office rendering mode should be enabled by the MSO feature in your license key.

The object also has a renderComments enumeration property that controls how comments should be handled in Microsoft Word or OpenDocument Text documents. Supported values:

• "default" - The rendering of the comments in the output file(s) will depend on the fileTypes.word.renderComments central configuration parameter.
• "render" - Force rendering of the comments in the output file(s).
• "hide" - Disable rendering of the comments in the output file(s).

The default is "default" (where output PDFs, images, and SVGs will visually show the comments if fileTypes.word.renderComments central configuration parameter set to "render" value). If you want to create output files where comments are not shown or hidden independent of the central configuration setting, specify one of the other options explicitly.

Here is a minimal example:

POST prizmdoc_server_base_url/v2/contentConverters
Content-Type application/json

{
    "input": {
        "sources": [
            {
                "fileId": "ek5Zb123oYHSUEVx1bUrVQ",
                "wordOptions": {
                    "trackedChanges": "preserve",
                    "renderComments": "default"
                }
            },
            {
                "fileId": "ElkNzWtrUJp4rXI5YnLUgw",
                "wordOptions": {
                    "trackedChanges": "acceptAll",
                    "renderComments": "hide"
                }
            }
        ],
        "dest": {
            "format": "pdf"
        }
    }
}

NOTE: See the Base URL for PrizmDoc Server topic for more information.

input.sources[n].powerPointOptions

The input.sources[n].powerPointOptions object will be considered only when the source is a supported Microsoft PowerPoint or OpenDocument Presentation format:

• ppt
• pptx
• pptm
• pot
• potx
• potm
• pps
• ppsx
• ppsm
• odp
• otp
• fodp

Otherwise it will be ignored. The object has a renderingMode enumeration property that controls how the document should be rendered. Supported values:

• "default" - The rendering mode will depend on the fileTypes.powerPoint.renderingMode central configuration parameter.
• "slides" - Put only slides into the output file(s).
• "slidesWithNotes" - Put slides along with speaker notes into the output file(s).

The default is "slides" (where output PDFs, images, and SVGs will contain slides only). If you want to create output files with speaker notes shown, please specify "slidesWithNotes" option.

Here is a minimal example:

POST prizmdoc_server_base_url/v2/contentConverters
Content-Type application/json

{
    "input": {
        "sources": [
            {
                "fileId": "eV3tAl3awOLE7i-s1FUkUA",
                "powerPointOptions": {
                    "renderingMode": "slides"
                }
            },
            {
                "fileId": "YJ6jG1EM8eT7TggX5TD8og",
                "wordOptions": {
                    "renderingMode": "slidesWithNotes"
                }
            }
        ],
        "dest": {
            "format": "pdf"
        }
    }
}

input.sources[n].rotation

The input.sources[n].rotation is supported only when the destination format is PDF. Supported values:

• 0
• 90
• 180
• 270

Here is a minimal example:

POST prizmdoc_server_base_url/v2/contentConverters
Content-Type application/json

{
    "input": {
        "sources": [
            {
                "fileId": "eV3tAl3awOLE7i-s1FUkUA",
                "pages": "1-3",
                "rotation": 90
            },
            {
                "fileId": "YJ6jG1EM8eT7TggX5TD8og",
                "rotation": 180
            }
        ],
        "dest": {
            "format": "pdf"
        }
    }
}

Error responses

When the input.sources[n].rotation is of invalid type/value, the errorCode will be "InvalidInput", and the errorDetails in the response body will be:

"errorDetails": {
    "at": "input.sources[0].rotation",
    "in": "body",
    "expected": {
        "enum": [0,90,180,270]
    }
}

When the input.dest.format is not "pdf", the errorCode will be "InvalidInput", and the errorDetails in the response body will be:

"errorDetails": {
    "at": "input.sources[0].rotation",
    "in": "body",
    "expected": {
        "enum": [0,90,180,270]
    },
    "when": [
        {
            "otherInput": {
                "in": "body",
                "at": "input.dest.format",
                "is": {
                    "value": "pdf"
                }
            }
        }
    ]
}

NOTE: See the Base URL for PrizmDoc Server topic for more information.

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.

The width and height of the recognized image should not exceed 32767 pixels.

Strikethrough text will not be recognized.

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.

input.dest.watermarks

Diagonal text watermark

Currently only diagonal text watermarks are supported. Each array item must be an object which conforms to the following:

Note that currently diagonal text watermarks are supported only when input.dest.format is "pdf".

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 lifetime is defined by the processIds.lifetime central configuration parameter.

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:

HTTP/1.1 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:

HTTP/1.1 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:

HTTP/1.1 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" }],
                "pageCount": 3
            }
        ]
    }
}

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

HTTP/1.1 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" }],
                "pageCount": 1
            },
            {
                "fileId": "+4b6QW90Fb9yjDak+ALFEg",
                "sources": [{ "fileId": "ek5Zb123oYHSUEVx1bUrVQ", "pages": "2" }],
                "pageCount": 1
            },
            {
                "fileId": "Lx/4z8AyJKV5eMjWKsBm5w",
                "sources": [{ "fileId": "ek5Zb123oYHSUEVx1bUrVQ", "pages": "3" }],
                "pageCount": 1
            }
        ]
    }
}

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
• DOCX
• XLSX

Note that the conversion from the source PDF to the output PDF file is implemented to remove all JavaScript during the source file processing. After the source file processing is complete, there is no JavaScript in the output PDF file(s).