PrizmDoc Viewer v13.11 Release - Updated
Viewing Sessions
API Reference > PAS REST API > Viewing Sessions

Introduction

Available URLs

URL Description
POST /ViewingSession Creates a viewing session.
PUT /ViewingSession/u{viewingSessionId}/SourceFile Uploads a document to the session.
PUT /v2/viewingSessions/{viewingSessionId}/sourceFile/original Uploads original document to the comparison viewing session.
PUT /v2/viewingSessions/{viewingSessionId}/sourceFile/revised Uploads revised document to the comparison viewing session.
GET /ViewingSession/u{viewingSessionId}/SourceFile Downloads the source document in use for a viewing session.
GET /v2/viewingSessions/{viewingSessionId}/sourceFile/original When viewing a comparison of two documents, downloads the first of the two source documents.
GET /v2/viewingSessions/{viewingSessionId}/sourceFile/revised When viewing a comparison of two documents, downloads the second of the two source documents.
GET /v2/viewingSessions/{viewingSessionId}/restrictions Returns information about any restrictions enforced by the server for the current viewing session.
POST /ViewingSession/u{viewingSessionId}/Replacement Replaces a viewing session with new parameters.

POST /ViewingSession

Routes key: PostViewingSession

Creates a new viewing session. At a high level, a viewing session takes a source document as input and produces HTML page content and document text as output.

Request

Request Headers

Name Description
Content-Type Should be application/json

Request Body

Successful Response

Response Body

JSON with metadata about the created viewing session.

Error Responses

Status Code JSON errorCode Description
403 "InvalidSecret" The provided Accusoft-Secret request header value did not match the value of secretKey in your PAS config file. Only applies when you are self-hosting PAS.
404 "DocumentNotFound" The specified document could not be found.
480 "InvalidInput" Input is invalid. See errorDetails in the response body.
480 "CannotChangeDocument" The viewing session already has an original source document.
480 "IncorrectUsage" The viewing session is already used for viewing of a single source document.
480 "FeatureNotLicensed" MSO enabled license is not installed.
480 "FeatureDisabled" Microsoft Office renderer is not configured.
480 "InputNotSupportedWithDocumentId" Input is not supported when creating a viewing session which auto-generates an associated viewing package in the background. See errorDetails in the response body.
480 "InputConflictsWithViewingPackage" Input conflicts with the value previously used to create the associated viewing package. See errorDetails in the response body.

Examples

Uploading the source document in a subsequent request

POST pas_base_url/ViewingSession
Content-Type: application/json

{
    "source": {
        "type": "upload",
        "displayName": "sample_2015-10-31T19:15:32Z.doc"
    }
}

Using a URL for the source document

POST pas_base_url/ViewingSession
Content-Type: application/json

{
    "source": {
        "type": "url",
        "url": "http://myserver/mydocument.docx",
        "headers": {
          "My-Custom-Header": "some value required by my server"
        },
        "acceptBadSslCertificate": false
    }
}

Using an existing viewing package

You can use an already-created viewing package to start a viewing session. The pre-converted viewable content will be immediately available and no work will be sent to PrizmDoc Server. See the PAS Viewing Package Creators API for more details about creating viewing packages and the PAS Viewing Packages API for more details about managing viewing packages.

POST pas_base_url/ViewingSession
Content-Type: application/json
{
    "source": {
        "type": "viewingPackage",
        "documentId": "doc_9495837910qc"
    }
}

Dynamically creating a viewing package in the background the first time a document is viewed

It is possible to ask PAS to use a viewing package if it exists and, if not, automatically start creating such a viewing package in the background so that it can be used by future viewing sessions. You do this by simply specifying a documentId.

For example, here is a POST which uses a source.type of "upload" but also specifies a documentId:

POST pas_base_url/ViewingSession
Content-Type: application/json
{
    "source": {
        "type": "url",
        "url": "http://myserver/mydocument.docx",
        "headers": {
          "My-Custom-Header": "some value required by my server"
        },
        "documentId": "doc_9495837910qc"
    }
}

If a viewing package exists for the given documentId, then it will be used and no conversion work will be performed. If a viewing package does not exist for the given documentId, then PAS will use PrizmDoc Server to prepare the content needed for this viewing session and also start creating a viewing package in the background. The application can continue to create viewing sessions in the same way for this document. Once the viewing package exists, PAS will simply use the contents of the package directly and stop sending conversion work to PrizmDoc Server.

Comparing two Microsoft Word documents

POST pas_base_url/ViewingSession
Content-Type: application/json

{
    "source": {
        "type": "comparison",
        "original": {
            "type": "upload",
            "displayName": "2019-10-07-original.docx"
        },
        "revised": {
            "type": "upload",
            "displayName": "2019-10-07-revised.docx"
        }
    }
}

PUT /ViewingSession/u{viewingSessionId}/SourceFile

Routes key: PutViewingSessionSourceFile

Uploads a document to the session.

Request

Request Headers

Name Description
Accusoft-Secret Required only if you are self-hosting PAS, must match the value of secretKey in your PAS config file.

Request Body

The bytes of the source document.

Successful Response

A simple HTTP 200 status code indicating the file was received.

Error Responses

Status Code JSON errorCode Description
403 "InvalidSecret" The provided Accusoft-Secret request header value did not match the value of secretKey in your PAS config file. Only applies when you are self-hosting PAS.

Example

Request

PUT pas_base_url/ViewingSession/u{viewingSessionId}/SourceFile
Accusoft-Secret: mysecretkey

<<file bytes>>

Response

HTTP/1.1 200 OK

PUT /v2/viewingSessions/{viewingSessionId}/sourceFile/original

Routes key: PutViewingSessionOriginalSourceFile

Used when viewing a comparison of two documents, uploads the first of the two documents, the original document.

Request

Request Headers

Name Description
Accusoft-Secret Required only if you are self-hosting PAS, must match the value of secretKey in your PAS config file.

Request Body

The bytes of the original document (for comparison with a revised document).

Successful Response

A simple HTTP 200 status code indicating the file was received.

Error Responses

Status Code JSON errorCode Description
404 - No viewing session with the provided viewingSessionId could be found.
403 "InvalidSecret" The provided Accusoft-Secret request header value did not match the value of secretKey in your PAS config file. Only applies when you are self-hosting PAS.
480 "CannotChangeDocument" The viewing session already has an original document assigned.
480 "UnsupportedFormatForComparison" The uploaded file was not a Word document (for comparison viewing, we currently only support "doc" and "docx" files).
480 "IncorrectUsage" For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you receive this error from this URL, it is because a single source document has already been provided.
480 "FeatureNotLicensed" The server's license does not allow the use of the MSO (Microsoft Office) feature, so document comparison is not possible.
480 "FeatureDisabled" The server has not been configured to allow the use of the Microsoft Office renderer, so document comparison is not possible.

Example

Request

PUT pas_base_url/v2/viewingSessions/{viewingSessionId}/sourceFile/original
Accusoft-Secret: mysecretkey

<<file bytes>>

Response

HTTP/1.1 200 OK

PUT /v2/viewingSessions/{viewingSessionId}/sourceFile/revised

Routes key: PutViewingSessionRevisedSourceFile

Used when viewing a comparison of two documents, uploads the second of the two documents, the revised document.

Request

Request Headers

Name Description
Accusoft-Secret Required only if you are self-hosting PAS, must match the value of secretKey in your PAS config file.

Request Body

The bytes of the revised document (for comparison with an original document).

Successful Response

A simple HTTP 200 status code indicating the file was received.

Error Responses

Status Code JSON errorCode Description
404 - No viewing session with the provided viewingSessionId could be found.
403 "InvalidSecret" The provided Accusoft-Secret request header value did not match the value of secretKey in your PAS config file. Only applies when you are self-hosting PAS.
480 "CannotChangeDocument" The viewing session already has a revised source document assigned.
480 "UnsupportedFormatForComparison" The uploaded file was not a Word document (for comparison viewing, we currently only support "doc" and "docx" files).
480 "IncorrectUsage" For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you receive this error from this URL, it is because a single source document has already been provided.
480 "FeatureNotLicensed" The server's license does not allow the use of the MSO (Microsoft Office) feature, so document comparison is not possible.
480 "FeatureDisabled" The server has not been configured to allow the use of the Microsoft Office renderer, so document comparison is not possible.

Example

Request

PUT pas_base_url/v2/viewingSessions/{viewingSessionId}/sourceFile/revised
Accusoft-Secret: mysecretkey

<<file bytes>>

Response

HTTP/1.1 200 OK

GET /ViewingSession/u{viewingSessionId}/SourceFile?ContentDispositionFilename={ContentDispositionFilename}

Routes key: GetSourceFile

Gets the source document in use for a viewing session.

Request

URL Parameters

Parameter Description
{viewingSessionId} The viewingSessionId which identifies the viewing session.
{ContentDispositionFilename} The filename as a URL-encoded string, without extension, to be used in the Content-Disposition response header (appropriate file extension such as doc or docx will automatically be added). By default, the value will be SourceFile.<ext>.

Response Headers

Name Description
Content-Disposition Indicates to a browser that the response body should be treated as a file download and specifies the filename the browser should use.
Content-Type The most-specific MIME type for the returned document or application/octet-stream otherwise.

Response Body

The raw bytes of the viewing session's source document.

Example

Request

GET pas_base_url/ViewingSession/uXYZ.../SourceFile?ContentDispositionFilename=MonthlySalesReport

Response

200 OK
Content-Type: application/msword
Content-Disposition: attachment; filename=MonthlySalesReport.docx; filename*=UTF-8''MonthlySalesReport.docx

<<file bytes>>

GET /v2/viewingSessions/{viewingSessionId}/sourceFile/original?contentDispositionFilename={contentDispositionFilename}

Routes key: GetOriginalSourceFile

When viewing a comparison of two documents, gets the original document used in the comparison. The document returned will be an identical copy of the document originally provided.

Request

URL Parameters

Parameter Description
{viewingSessionId} The viewingSessionId which identifies the viewing session.
{contentDispositionFilename} The filename as a URL-encoded string, without extension, to be used in the Content-Disposition response header (appropriate file extension such as doc or docx will automatically be added). By default, the value will be OriginalSourceFile.<ext>.

Response Headers

Name Description
Content-Disposition Indicates to a browser that the response body should be treated as a file download and specifies the filename the browser should use.
Content-Type The most-specific MIME type for the returned document or application/octet-stream otherwise.

Response Body

The raw bytes of the first of the two documents being viewed as a comparison, the original document.

Error Responses

Status Code JSON errorCode Description
404 - No viewing session with the provided viewingSessionId could be found.
480 "DocumentNotProvidedYet" An original document has not been provided to the viewing session yet.
480 "IncorrectUsage" For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you receive this error from this URL, it is because a single source document was provided for viewing, so there will never be an original comparison document to get.

Example

Request

GET pas_base_url/v2/viewingSessions/XYZ.../sourceFile/original?contentDispositionFilename=OldMonthlySalesReport

Response

200 OK
Content-Type: application/msword
Content-Disposition: attachment; filename=OldMonthlySalesReport.docx; filename*=UTF-8''OldMonthlySalesReport.docx

<<file bytes>>

GET /v2/viewingSessions/{viewingSessionId}/sourceFile/revised?contentDispositionFilename={contentDispositionFilename}

Routes key: GetRevisedSourceFile

When viewing a comparison of two documents, gets the revised document used in the comparison. The document returned will be an identical copy of the document originally provided.

The response will set the Content-Type header to the most-specific MIME type it can or application/octet-stream otherwise.

Request

URL Parameters

Parameter Description
{viewingSessionId} The viewingSessionId which identifies the viewing session.
{contentDispositionFilename} The filename as a URL-encoded string, without extension, to be used in the Content-Disposition response header (appropriate file extension such as doc or docx will automatically be added). By default, the value will be RevisedSourceFile.<ext>.

Response Headers

Name Description
Content-Disposition Indicates to a browser that the response body should be treated as a file download and specifies the filename the browser should use.
Content-Type The most-specific MIME type for the returned document or application/octet-stream otherwise.

Response Body

The raw bytes of the second of the two documents being viewed as a comparison, the revised document.

Error Responses

Status Code JSON errorCode Description
404 - No viewing session with the provided viewingSessionId could be found.
480 "DocumentNotProvidedYet" A "revised" document has not been associated with the viewing session yet.
480 "IncorrectUsage" For any new viewing session, you can give it either 1) a single source document for viewing or 2) two documents (original and revised) which should be viewed as a comparison, but you cannot do both. If you receive this error from this URL, it is because a single source document was provided for viewing, so there will never be a revised comparison document to get.

Example

Request

GET pas_base_url/v2/viewingSessions/XYZ.../sourceFile/revised?contentDispositionFilename=NewMonthlySalesReport

Response

HTTP/1.1 200 OK
Content-Type: application/msword
Content-Disposition: attachment; filename=NewMonthlySalesReport.docx; filename*=UTF-8''NewMonthlySalesReport.docx

<<file bytes>>

GET /v2/viewingSessions/{viewingSessionId}/restrictions

Returns information about any restrictions enforced by the server for the current viewing session.

Request

URL Parameters

Parameter Description
{viewingSessionId} The viewingSessionId which identifies the viewing session.

Successful Response

JSON with information about any restrictions currently in place for the viewing session:

Example Responses

When the product is licensed and the form detection feature is available

HTTP/1.1 200 OK
Content-Type: application/json

{
  "delayEnabled": false,
  "downloadDisabled": false,
  "markupSavingDisabled": false,
  "markupLoadingDisabled": false,
  "contentConvertersDisabled": false,
  "markupBurnersDisabled": false,
  "formExtractorsDisabled": false,
  "formInfoDisabled": false
}

When the product is unlicensed (evaluation mode), and 9 seconds of initial delay are remaining:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "delayEnabled": true,
  "delaySecondsRemaining": 9,
  "downloadDisabled": true,
  "markupSavingDisabled": true,
  "markupLoadingDisabled": true,
  "contentConvertersDisabled": true,
  "markupBurnersDisabled": true,
  "formExtractorsDisabled": true,
  "formInfoDisabled": true
}

POST /ViewingSession/u{viewingSessionId}/Replacement

Routes key: CreateViewingSessionReplacement

Replace the existing viewing session with a new one that has a new password parameter value. The other original viewing session parameters are preserved. If a source document is uploaded it is attached to the newly created viewing session with a new password. The old viewing session is stopped.

The replacement API is useful when a session is errored because of either an invalid or missing password, and you want to replace it with a new session with the same parameters against the same document but with a modified password.

Request

Request Headers

Name Description
Content-Type Should be application/json

Request Body

URL Parameters

Parameter Description
{viewingSessionId} The viewingSessionId which identifies the viewing session.

Successful Response

Response Body

JSON with metadata about the created viewing session.

Error Responses

Status Code Reason Phrase Description
403 The session is invalid or has expired You requested a valid {viewingSessionId} but it is no longer available.
500 Internal Server Error Can occur if you forget to prefix the {viewingSessionId} portion of the URL with u, or if you simply request an invalid {viewingSessionId}.

Some error responses will have a JSON body with an errorCode and errorDetails:

Status Code JSON errorCode Description
480 "PropertyNotReplaceable" Unsupported property to replace was used. See errorDetails in the response body.

Example

Request

POST pas_base_url/ViewingSession/uXYZ.../Replacement
Content-Type: application/json

{
    "password":"123"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
    "viewingSessionId": "THMMytF4ACHrxmN2bXj4vahx4Gnwly_kEeFt20XtRau-z43pPHIjUy5JXJ05Wj1MaqvdfsXp98JxIk7ALWkukg"
}