PrizmDoc® Viewer v14.0 Release - Updated
PrizmDoc Viewer / API Reference / PrizmDoc Server REST API / Application Development / Content Conversion Service
In This Topic
    Content Conversion Service
    In This Topic

    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

    URL Description
    POST /v2/contentConverters Create and start a content conversion
    GET /v2/contentConverters/{processId} Get the status of a content conversion

    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

    Name Value Details
    Content-Type application/json required
    Accusoft-Affinity-Token

    The affinityToken of the work files involved in the input to the process.

    Example: rcqmuB9pAa8+4V7fhO1SXzawy/YMQU1g8lLdNDe5l7w=

    Required when server clustering is enabled. Providing this value is important to ensuring the process will execute on the machine where the input work files actually exist.

    NOTE: If you do not provide the required Accusoft-Affinity-Token, the POST itself will succeed but the process itself will likely fail.

    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.

    Name Description Details
    input.sources[n].fileId

    Id of the WorkFile to use as input.

    See Supported Input File Formats

    string, required

    Example: "ek5Zb123oYHSUEVx1bUrVQ"

    input.sources[n].pages

    Page numbers and/or page ranges separated by commas.

    Currently pages is only supported when the destination format is pdf or tiff, and is ignored otherwise. We expect this to change in a future version, in which case pages will be supported for other destination formats.

    string, optional

    Example: 1,3,5-10

    input.sources[n].password

    Password to open the document.

    Currently password is only supported when the source format is PDF, MS Word, MS Excel, MS PowerPoint or OpenDocument, and is ignored otherwise. Please note that only Office Open XML versions of MS Word, MS Excel and MS PowerPoint are supported when fidelity.msOfficeDocumentsRenderer is set to "libreoffice". We expect this to change in a future version, in which case password will be supported for other source formats.

    string, optional

    Example: "secret"

    input.sources[n].wordOptions Additional options of a Microsoft Word compatible source file format. object, optional
    input.sources[n].powerPointOptions Additional options of a Microsoft PowerPoint compatible source file format. object, optional
    input.sources[n].rotation Rotation angle in degrees to be applied on the source pages if the destination format is PDF. If the pages are not specified, all pages of the document will be rotated, otherwise the rotation will be applied only on the specified page(s).The default is 0. integer, optional

    input.sources[n].wordOptions

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

    • doc
    • docx
    • docm
    • dot
    • dotx
    • dotm

    Otherwise it will be ignored. The object has a trackedChanges enumeration property that controls how tracked changes should be handled. 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.

    NOTE: In a future release the default value for input.sources[n].wordOptions.trackedChanges will be changed to "acceptAll" in order to be more consistent with LibreOffice rendering mode.

    Here is a minimal example:

    POST prizmdoc_server_base_url/v2/contentConverters
    Content-Type application/json
    
    {
        "input": {
            "sources": [
                {
                    "fileId": "ek5Zb123oYHSUEVx1bUrVQ",
                    "wordOptions": {
                        "trackedChanges": "preserve"
                    }
                },
                {
                    "fileId": "ElkNzWtrUJp4rXI5YnLUgw",
                    "wordOptions": {
                        "trackedChanges": "acceptAll"
                    }
                }
            ],
            "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 format:

    • ppt
    • pptx
    • pptm
    • pot
    • potx
    • potm
    • pps
    • ppsx
    • ppsm

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

    • "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.

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

    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.

    Name Description Details
    input.src.fileId

    Id of the WorkFile to use as input.

    See Supported Input File Formats

    string, required

    Example: "ek5Zb123oYHSUEVx1bUrVQ"

    input.dest

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

    Name Description Details
    input.dest.format

    Output file format.

    Supported values:

    • "jpeg"
    • "pdf"
    • "png"
    • "svg"
    • "tiff"
    • "docx"
    • "xlsx"

    Currently "docx" destination format is only supported when the source format is PDF. This functionality also requires the Microsoft Office rendering mode to be enabled by the MSO feature in your license key.

    The "xlsx" destination format is only supported when the source format is either XLS or CSV. This functionality also requires the Microsoft Office rendering mode to be enabled by the MSO feature in your license key.

    string, required
    input.dest.jpegOptions Additional options when input.dest.format is "jpeg". object, optional
    input.dest.pdfOptions Additional options when input.dest.format is "pdf". object, optional
    input.dest.pngOptions Additional options when input.dest.format is "png". object, optional
    input.dest.tiffOptions Additional options when input.dest.format is "tiff". object, optional
    input.dest.header Header to append to each page of the output. The page dimensions will be expanded to allow space for the additional header content (the original page content will be unaltered). object, optional
    input.dest.footer Footer to be append to each page of the output. The page dimensions will be expanded to allow space for the additional footer content (the original page content will be unaltered). object, optional
    input.dest.watermarks Watermarks to apply to each page of the output. object, optional

    input.dest.jpegOptions

    Name Description Details
    input.dest.jpegOptions.maxWidth Maximum pixel width of the output JPEG image, expressed as a CSS-style string, e.g. "800px". When specified, the output will never be wider than the specified value and its aspect ratio will be preserved.

    string, optional

    Example: "800px"

    input.dest.jpegOptions.maxHeight Maximum pixel height of the output JPEG image, expressed as a CSS-style string, e.g. "600px". When specified, the output will never be taller than the specified value and its aspect ratio will be preserved.

    string, optional

    Example: "600px"

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

    input.dest.pdfOptions

    Name Description Details
    input.dest.pdfOptions.forceOneFilePerPage

    When true, forces output to be a collection of single-page PDF files (rather than a single multi-page PDF file).

    Default is false.

    boolean, optional
    input.dest.pdfOptions.ocr

    Options for text recognition. Applies when the source file is raster or image-based PDF (a PDF which has a single raster image on each page). > NOTE: If you are attempting to make a searchable PDF from an existing PDF document, please note that the source PDF file should be an image-only PDF. PrizmDoc will not create a searchable file from already-existing vector content.

    object, optional
    input.dest.pdfOptions.ocr.language

    Language to recognize. Currently, only English is supported. Value must be "english".

    string, required
    input.dest.pdfOptions.ocr.defaultDpi

    Default DPI to use when the input does not specify DPI information.

    Default is { x: 300, y: 300 }

    object, optional
    input.dest.pdfOptions.ocr.defaultDpi.x

    Horizontal DPI value.

    integer, required
    input.dest.pdfOptions.ocr.defaultDpi.y

    Vertical DPI value.

    integer, required

    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

    Name Description Details
    input.dest.pngOptions.maxWidth Maximum pixel width of the output PNG image, expressed as a CSS-style string, e.g. "800px". When specified, the output will never be wider than the specified value and its aspect ratio will be preserved.

    string, optional

    Example: "800px"

    input.dest.pngOptions.maxHeight Maximum pixel height of the output PNG image, expressed as a CSS-style string, e.g. "600px". When specified, the output will never be taller than the specified value and its aspect ratio will be preserved.

    string, optional

    Example: "600px"

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

    input.dest.tiffOptions

    Name Description Details
    input.dest.tiffOptions.forceOneFilePerPage

    When true, forces output to be a collection of single-page TIFF files (rather than a single multi-page TIFF file).

    Default is false.

    boolean, optional
    input.dest.tiffOptions.maxWidth Maximum pixel width of each page of the output TIFF, expressed as a CSS-style string, e.g. "800px". When specified, the output pages are guaranteed to never be wider than the specified value and their aspect ratio will be preserved.

    string, optional

    Example: "800px"

    input.dest.tiffOptions.maxHeight Maximum pixel height of each page of the output TIFF, expressed as a CSS-style string, e.g. "600px". When specified, the output pages are guaranteed to never be taller than the specified value and their aspect ratio will be preserved.

    string, optional

    Example: "600px"

    input.dest.tiffOptions.compression.type

    Output image compression type to use.

    Supported values:

    • "auto" - Automatically choose output compression type based on the source document(s).
    • "lzw" - Force the use of LZW compression. LZW is a lossless compression format which preserves transparency.
    • "jpeg" - Force the use of JPEG compression. JPEG is a lossy compression format ideal for photographs. "jpeg" compression can only be used when input.dest.tiffOptions.color.mode is "auto" (the default), "grayscale", or "rgb".
    • "group4" - Force the use of Group 4 compression. Group 4 is only for bitonal (black and white) output. As such, "group4" can only be used when input.dest.tiffOptions.color.mode is "auto" (the default) or "bitonal".
    Default is "auto"

    string, optional

    Example: "lzw"

    input.dest.tiffOptions.color.mode

    Output image color mode to use.

    Supported values:

    • "auto" - Automatically choose output color mode based on the source document(s).
    • "bitonal" - Force the use of bitonal color mode, limiting the output to black and white only, 1-bit per pixel.
    • "grayscale" - Force the use of grayscale color mode, limiting the output to grayscale colors, 8-bits per pixel.
    • "indexed" - Force the use of indexed color mode, limiting the output to 256 colors, 8-bits per pixel.
    • "rgb" - Force the use of RGB color, 24-bits per pixel.
    Default is "auto".

    string, optional

    Example: "indexed"

    input.dest.tiffOptions.dpi

    Output image resolution (in dots per inch) to use. When specified (it should be a positive integer), the output TIFF image will have requested dpi value and will be scaled if necessary.

    Please note that input.dest.tiffOptions.maxWidth and input.dest.tiffOptions.maxHeight have precedence over input.dest.tiffOptions.dpi, so if either of those parameters is present, the output image will be resized according to them, and the new resolution will be assigned without additional resizing. Otherwise, if neither of maxWidth/maxHeight is specified, the dpi resolution will be applied as follows:

    • If the source image has a valid resolution, the output image will be resized by scale factor input.dest.tiffOptions.dpi / imageCurrentResolution
    • If the source image has no valid resolution, the new resolution will be assigned without resizing

    integer, optional

    Example: 300

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

    input.dest.header

    Name Description Details
    input.dest.header.lines

    Text content for the header. This is a multi-dimensional array that allows you to easily position text left, center, and right. The first string in any inner array will always be placed on the left (left-justified), the second string placed in the center (center-justified), and the third string placed on the right (right-justified). The number of items in the outer array defines the total number of text lines. You may provide between one and three lines of text for a header.

    array, optional
    input.dest.header.fontFamily

    Font family to use (e.g. "Courier"). The font name provided must be present on the server to be applied.

    string, optional
    input.dest.header.fontSize

    Font size in points. Value must be a string with a number followed by "pt" (e.g. "12pt").

    string, optional
    input.dest.header.color

    Text color. Value must be in 6-digit CSS hex color format (e.g. "#FF0000").

    string, optional

    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

    Name Description Details
    input.dest.footer.lines

    Text content for the footer. This is a multi-dimensional array that allows you to easily position text left, center, and right. The first string in any inner array will always be placed on the left (left-justified), the second string placed in the center (center-justified), and the third string placed on the right (right-justified). The number of items in the outer array defines the total number of text lines. You may provide between one and three lines of text for a footer.

    array, optional
    input.dest.footer.fontFamily

    Font family to use (e.g. "Courier"). The font name provided must be present on the server to be applied.

    string, optional
    input.dest.footer.fontSize

    Font size in points. Value must be a string with a number followed by "pt" (e.g. "12pt").

    string, optional
    input.dest.footer.color

    Text color. Value must be in 6-digit CSS hex color format (e.g. "#FF0000").

    string, optional

    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:

    Name Description Details
    type

    Must be set to "diagonalText" to indicate the object represents a diagonal text watermark.

    string, required
    text

    Actual text of the watermark. To compose multiline text put new line characters (\n) in corresponding places. Within the string, you can use the following special tokens to insert dynamic values:

    • {{pageNumber}} - Will be replaced with the current page number
    • {{pageCount}} - Will be replaced with the total number of pages
    string, required
    opacity

    Opacity of the watermark. 1.0 is completely opaque, 0.0 is completely transparent. Default is 1.0.

    number, optional
    color

    Text color. Can be any valid CSS color name (like "red") or hex value (like "#FF0000"). Default is "black".

    string, optional
    fontFamily

    Specifies the name of the font that is used for the watermark (e.g. "fontFamily": "Courier"). The font name provided must be present on the server to be applied.

    string, optional
    fontSize

    Font size in points. Value must be a string with a number followed by "pt" (e.g. "12pt").

    string, optional
    fontWeight

    Font weight.

    Supported values:

    • "normal"
    • "bold"

    Default is "normal".

    string, optional
    fontStyle

    Font style.

    Supported values:

    • "normal"
    • "italic"

    Default is "normal".

    string, optional
    textDecoration

    Text decoration

    Supported values:

    • "none"
    • "underlined"

    Default is "none".

    string, optional
    slope

    Controls the text angle.

    Supported values:

    • "up" - Text will start in the lower-left corner of the page and extend upwards to the upper-right corner of the page.
    • "down"- Text will start in the upper-left corner of the page and extend downwards to the lower-right corner of the page.

    Default is "up".

    string, optional

    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

    Name Description Details
    processId The id of the contentConverter resource which represents the file conversion operation. string
    expirationDateTime The date and time (in ISO 8601 Extended Format) when the contentConverter resource will be deleted.

    string

    Example: "2015-12-17T20:38:39.796Z"

    state

    The current state of the conversion process, which will be one of the following:

    • "processing" - The conversion is still in progress.
    • "complete" - The conversion has completed successfully.
    • "error" - The conversion failed due to a problem.

    For the initial POST, this value will almost always be "processing". Results are typically only available with a subsequent GET.

    string
    percentComplete An integer from 0 to 100 that indicates what percentage of the conversion is complete.

    integer

    Example: 0

    errorCode An error code string if a problem occurred during the conversion process.

    string

    Example: "InvalidInput"

    affinityToken Affinity token echoed from request header. This value will only be present if PrizmDoc Server is running in cluster mode.

    string

    Example: "rcqmuB9pAa8+4V7fhO1SXzawy/YMQU1g8lLdNDe5l7w="

    HTTP Status Codes and Response JSON Error Codes

    HTTP Status "state" in response JSON body "errorCode" in response JSON body Description
    200 processing - The contentConverter was created and the conversion process was started.
    400 error CouldNotReadRequestData Could not read request data.
    405 - - POST HTTP method was not used.
    480 error InvalidJson Json error details are in errorDetails.
    480 - InvalidDimensionValue Invalid dimension value specified for rasterization. See details in errorDetails.
    480 - InvalidInput Invalid input. Invalid request data is referenced in the errorDetails.
    480 - InvalidPageSyntax Invalid page specification. See errorDetails.
    480 - ForceOneFilePerPageNotSupportedWhenUsingHeaderOrFooter forceOneFilePerPage mode is not supported when using header or footer options. Supported forceOneFilePerPage option is referenced in errorDetails.
    480 - MaxWidthOrMaxHeightMustBeSpecifiedWhenRasterizingCadInput Max width or max height must be specified when rasterizing CAD input. See errorDetails.
    480 - MissingInput Missing input. See errorDetails.
    480 - MultipleSourcesAreNotSupportedForThisDestinationFormat Multiple source files or pages are not supported for this destination format.
    480 - MultipleSourceDocumentsNotSupportedWhenUsingHeaderOrFooter Multiple source documents are not supported when using header or footer.
    480 - PagesPropertyNotSupportedWhenUsingHeaderOrFooter Pages property is not supported for conversion with header or footer. The property is referenced in errorDetails
    480 - UnrecognizedExpression Unrecognized expression. See errorDetails.
    480 - UnsupportedConversion Unsupported conversion. See errorDetails.
    480 - UnsupportedDestinationFormatWhenUsingHeaderOrFooter Unsupported destination format when using header or footer. Supported destination formats are listed in errorDetails.
    480 - UnsupportedDestinationFormatWhenUsingWatermarks Unsupported destination format when using watermarks. Supported destination formats are listed in errorDetails.
    480 - UnsupportedSourceFileFormat Unsupported source file format. Unsupported file is referenced in errorDetails.
    480 - UnsupportedSourceFileFormatForOCR Unsupported source file format for OCR. Unsupported file is referenced in errorDetails.
    480 - WorkFileDoesNotExist Specified work file does not exist.
    480 - FeatureNotLicensed The server's license does not allow the use of the requested feature. The unlicensed feature will be referenced by the errorDetails object in the response.
    480 - FeatureDisabled Occurs when using an option that is not supported by the server's configuration (such as trying to set certain wordOptions or powerPointOptions when the server is not using Microsoft Office for rendering). See the errorDetails in the response for the specific input value which could not be used.
    480 - LicenseCouldNotBeVerified The server's license could not be verified. If you are evaluating the product without a license, the product is running in evaluation mode and this particular part of the product is unavailable without a license. If you have a license, make sure you configured your license correctly, that your license has not expired, and that you have not exceeded any license limits (such as, for a Cloud License, the total number of logical CPU cores in use).
    580 - InternalServiceError Internal service error. This error can be returned for a number of different reasons. Please contact Customer Support.

    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

    Name Description Details
    processId The processId for a particular contentConverter. This processId was returned in the response for the initial POST. string, required

    Request Headers

    Name Value Details
    Accusoft-Affinity-Token

    Affinity token returned in post response body for content converter specified by processId parameter.

    Example: "rcqmuB9pAa8+4V7fhO1SXzawy/YMQU1g8lLdNDe5l7w="

    Only used if PrizmDoc Server is running in cluster mode.

    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

    Name Description Details
    processId The id of the contentConverter resource which represents the file conversion operation. string
    expirationDateTime The date and time (in ISO 8601 Extended Format) when the contentConverter resource will be deleted.

    string

    Example: "2015-12-17T20:38:39.796Z"

    state

    The current state of the conversion process, which will be one of the following:

    • "processing" - The conversion is still in progress.
    • "complete" - The conversion has completed successfully.
    • "error" - The conversion failed due to a problem.
    string
    percentComplete An integer from 0 to 100 that indicates what percentage of the conversion is complete.

    integer

    Example: 0

    errorCode An error code string if a problem occurred during the conversion process.

    string

    Example: "CouldNotConvertFile"

    affinityToken Affinity token echoed from request header. This value will only be present if PrizmDoc Server is running in cluster mode.

    string

    Example: "rcqmuB9pAa8+4V7fhO1SXzawy/YMQU1g8lLdNDe5l7w="

    Conversion Output Details

    Name Description Details
    output.results An array of objects, one for each output file created. object
    output.results[n].fileId The WorkFile id for an output file. Use this id to download the output file using the WorkFile API. string
    output.results[n].pageCount The total number of pages in the output file. integer
    output.results[n].sources An array of objects, one for each source file which contributed to this output file. array
    output.results[n].sources[n].fileId The WorkFile id of the source input file. string
    output.results[n].sources[n].pages

    The page or pages used from the source file.

    This will be a string value using one-based indexing. For example, if the output file represents page 2 of the source document, pages would have a value of "2". If the output file represents all 20 pages of a source document, pages would have a value of "1-20".

    string

    Examples: "1-3" or "2"

    output.results[n].src (deprecated) An array with a single object which corresponds to input.src. This will only appear in the output if you used the deprecated input.src property instead of the new input.sources in the original POST request. array

    HTTP Status Codes and Response JSON Error Codes

    HTTP status "state" in response JSON body "errorCode" in response JSON body Description
    200 processing errorCode: -
    errorCode Location: -
    Additional errorCode: -
    The contentConverter was created and the conversion process was started.
    200 complete errorCode: -
    errorCode Location: -
    Additional errorCode: -
    The conversion process was completed.
    200 complete errorCode: -
    errorCode Location: output.results[n].errorCode
    Additional errorCode: NoSuchPage
    No such page. Problem fileId and page number are listed in output.results[n].sources[0].fileId, output.results[n].sources[0].page.
    200 error errorCode: CouldNotConvert
    errorCode Location: output.results[n].errorCode
    Additional errorCode: CouldNotConvertFile
    Could not convert file. Problem fileId is listed in output.results[n].sources[0].fileId.
    200 error errorCode: CouldNotConvert
    errorCode Location: output.results[n].errorCode
    Additional errorCode: CouldNotConvertPage
    Could not convert page. Problem fileId and page number are listed in output.results[n].sources[0].fileId, output.results[n].sources[0].page.
    200 error errorCode: CouldNotConvert
    errorCode Location: output.results[n].errorCode
    Additional errorCode: InvalidPassword
    Password is incorrect or missing. Problem fileId, page number and password if it was passed are listed in output.results[n].sources[0].fileId, output.results[n].sources[0].page, output.results[n].sources[0].password.
    200 error errorCode: CouldNotConvert
    errorCode Location: output.results[0].errorCode
    Additional errorCode: RequestedHeaderOrFooterFontIsNotAvailable
    Requested header or footer font is not available. Name of the font which is not available is listed in input.dest.header.fontFamily or input.dest.footer.fontFamily.
    200 error errorCode: CouldNotConvert
    errorCode Location: output.results[0].errorCode
    Additional errorCode: RequestedWatermarkFontIsNotAvailable
    Requested watermark font is not available. Name of the font which is not available is listed in input.dest.watermarks[n].fontFamily.
    200 error errorCode: CouldNotConvertAllFilesOrPages
    errorCode Location: output.results[n].errorCode
    Additional errorCode: One or more occurrences of either of the following codes: CouldNotConvertFile, CouldNotConvertPage, NoSuchPage, InvalidPassword
    Could not convert all files or pages.
    For CouldNotConvertFile error, problem fileId is listed in output.results[n].sources[0].fileId.
    For CouldNotConvertPage, InvalidPassword and NoSuchPage errors, problem fileId and pageNumber are listed in output.results[n].sources[0].fileId, output.results[n].sources[0].page.
    404 - errorCode: ContentConverterDoesNotExist
    errorCode Location: -
    Additional errorCode: -
    Content converter does not exist. Invalid processId was specified in the request.
    405 - errorCode: -
    errorCode Location: -
    Additional errorCode: -
    POST HTTP method was not used.
    580 - errorCode: InternalServiceError
    errorCode Location: -
    Additional errorCode: -
    Internal service error. This error can be returned for a number of different reasons. Please contact Support.

    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).