Content Converters

POST /v2/viewingSessions/{viewingSessionId}/contentConverters

Routes key: CreateContentConverterV2

Starts a conversion process for the source document of a particular viewing session. This URL has the following parameters:

Parameter	Description
viewingSessionId	The ID provided in the response from `POST /ViewingSession`.

Request

Body: Empty. An error will be returned if any data is present.

Note: PDF is currently the only supported destination format. A successful response will include several input properties as shown below. A future release will allow these properties to be set in the request body to create various kinds of output.

Response

Body: a JSON object with the following properties:

Property	Type	Description
input	{object}	An object that specifies the input used for the conversion.
input.dest	{object}	An object that specifies the destination file format and any additional details which control how the content is converted.
input.dest.format	{string}	Specifies the output file format.
input.dest.pdfOptions	{object}	An object that specifies additional options when `input.dest.format` is "pdf".
input.dest.pdfOptions.forceOneFilePerPage	{boolean}	If true, the conversion process will produce single-page PDF files, one file for each page of content (instead of a single PDF with multiple pages). Default is false.
input.sources	{object}	An array of objects, one for each input file.
input.sources[n].pages	{string}	The page numbers and/or page ranges, separated by commas, of the source document to convert.
processId	{string}	The id of the contentConverter resource which represents the file conversion operation.
state	{string}	The current state of the conversion process, which will be one of the following: "processing", "complete", or "error". If "processing", the conversion is still in progress. If "complete", the conversion has completed successfully. If "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.
percentComplete	{integer}	An integer from 0 to 100 that indicates what percentage of the conversion is complete.
errorCode	{string}	An error code string if a problem occurred during the conversion process.

Examples

POST http://localhost:3000/v2/viewingSessions/ZGZhc2RmYXNkZmFzZGZkcw/contentConverters

Successful Response:

200 OK
Content-Type: application/json
{
    "input": {
        "dest": {
            "format": "pdf",
            "pdfOptions": {
                "forceOneFilePerPage": false
            }
        },
        "sources": [
            {
                "pages": ""
            }
        ]
    },
    "expirationDateTime": "2015-11-04T19:20:09.280Z",
    "processId": "mxivIVSw7UhtL1yWwt3QEA",
    "state": "processing",
    "percentComplete": 0
}

Errored Responses:

When a response with a status code of 580 is received check the response body for details:

580 InternalError
Content-Type: application/json
{ 
    "errorCode": "InternalError"
}

When a viewing session does not exist for the given viewingSessionId:

404 Not Found

When any data is present in the body of the request:

480 ReservedInput
{
    "errorCode": "ReservedInput",
    "errorDetails": {
        "in": "body"
    }
}

GET /v2/viewingSessions/{viewingSessionId}/contentConverters/{processId}

Routes key: PollContentConverterV2

Gets the status of the specific converter process. This URL has the following parameters:

Parameter	Description
viewingSessionId	The ID provided in the response from `POST /ViewingSession`.
processId	The ID provided in the response from `POST /v2/viewingSessions/{viewingSessionId}/contentConverters`.

Response

Body: a JSON object with the following properties:

Property	Type	Description
input	{object}	An object that specifies the input used for the conversion.
input.dest	{object}	An object that specifies the destination file format and any additional details which control how the content is converted.
input.dest.format	{string}	Specifies the output file format.
input.dest.pdfOptions	{object}	An object that specifies additional options when `input.dest.format` is "pdf".
input.dest.pdfOptions.forceOneFilePerPage	{boolean}	If true, the conversion process will produce single-page PDF files, one file for each page of content (instead of a single PDF with multiple pages). Default is false.
input.sources	{object}	An array of objects, one for each input file.
input.sources[n].pages	{string}	The page numbers and/or page ranges, separated by commas, of the source document to convert.
processId	{string}	The id of the contentConverter resource which represents the file conversion operation.
state	{string}	The current state of the conversion process, which will be one of the following: "processing", "complete", or "error". If "processing", the conversion is still in progress. If "complete", the conversion has completed successfully. If "error", the conversion failed due to a problem.
percentComplete	{integer}	An integer from 0 to 100 that indicates what percentage of the conversion is complete.
errorCode	{string}	An error code string if a problem occurred during the conversion process.
output.results	{object}	An array of objects, one for each output file created. The 0-based index of each output file will be used in the URL `GET /v2/viewingSessions/{viewingSessionId}/contentConverters/{processId}/results/{index}/file` to retrieve the contents of each file.
output.results[n].sources	{object}	An array of objects, one for each source file which contributed to this output file.
output.results[n].sources[n].pages	{string}	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".

Examples

GET http://localhost:3000/v2/viewingSessions/ZGZhc2RmYXNkZmFzZGZkcw/contentConverters/mxivIVSw7UhtL1yWwt3QEA

Successful Response:

When the converter process completes with no conversion failures:

200 OK
Content-Type: application/json
{
    "input": {
        "dest": {
            "format": "pdf",
            "pdfOptions": {
                "forceOneFilePerPage": false
            }
        },
        "sources": [
            {
                "pages": ""
            }
        ]
    },
    "processId": "mxivIVSw7UhtL1yWwt3QEA",
    "state": "complete",
    "percentComplete": 100,
    "output": {
        "results": [
            {
                "fileId": "eOsJIqI8aHkxVV0yJug",
                "sources": [
                    {
                        "pages": "1-4"
                    }
                ]
            }
        ]
    }
}

When the converter process completes with a failure:

200 OK
Content-Type: application/json
{
    "input": {
        "dest": {
            "format": "pdf",
            "pdfOptions": {
                "forceOneFilePerPage": false
            }
        },
        "sources": [
            {
                "pages": ""
            }
        ]
    },
    "processId": "mxivIVSw7UhtL1yWwt3QEA",
    "state": "error",
    "percentComplete": 100,
    "errorCode": "CouldNotConvert",
    "output": {
        "results": [
            {
                "errorCode": "CouldNotConvertPage",
                "sources": [
                    {
                        "pages": "3"
                    }
                ]
            }             
        ]
    }
}

Errored Responses:

When a response with a status code of 580 is received check the response body for details:

580 InternalError
Content-Type: application/json
{ 
    "errorCode": "InternalError"
}

When a converter process does not exist for the given processId:

404 Not Found

GET /v2/viewingSessions/{viewingSessionId}/contentConverters/{processId}/results/{index}/file?ContentDispositionFilename={fileName}

Routes key: GetContentConverterOutputFileV2

Gets the contents of a file produced by the converter process. This URL has the following parameters:

Parameter	Description
viewingSessionId	The ID provided in the response from `POST /ViewingSession`.
processId	The ID provided in the response from `POST /v2/viewingSessions/{viewingSessionId}/contentConverters`.
index	The 0-based index of the result file, originating from its position in the `response.output.results` array in the response from `GET /v2/viewingSessions/{viewingSessionId}/contentConverters/{processId}`.
fileName	The value that will be set for the `Content-Disposition: filename` header property in the response.

Examples

GET http://localhost:3000/v2/viewingSessions/ZGZhc2RmYXNkZmFzZGZkcw/contentConverters/mxivIVSw7UhtL1yWwt3QEA/results/0/file?ContentDispositionFilename=MyFile

Successful Response:

200 OK
Content-Disposition: attachment; filename=MyFile.pdf
Content-Type: {content type of the specific document}

Errored Responses:

When an output file does not exist for the given index:

404 Not Found