Introduction

The viewing sessions REST API is used by your application every time you need to show a document with our viewer.

A viewing session is a temporary resource. At a high level, it takes a source document as input and then, while the viewing session exists, it is able to produce document content in a form that can be displayed in the browser. Creating a viewing session (POST /ViewingSession) is very fast. Any document conversion work necessary will happen in the background after the viewing session has been created.

Our viewer, running in the browser, always makes requests for document content via an existing viewing session. So, to render HTML containing our viewer, your application must first create a viewing session. For more information about this, see Getting Started with Document Viewing.

Available URLs

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

Request Body

• source (Object) Object describing a source document where it comes from, such as local documents, documents specified via URL, etc. Properties relevant to PrizmApplicationService will reside in this object.
  • When uploading the source document in a subsequent request:
    • type (String) Required. Set to upload.
    • displayName (String) Required. Unique filename, including the extension, for the document that will be uploaded.

      IMPORTANT: You must use a value which is specific for the document you are going to upload. For optimal performance, you should NEVER use the same value for two different documents. We use this value internally (when running in clustered mode) to determine which machine in the cluster this viewing session should be assigned to. This allows us to ensure that viewing sessions with the same displayName can be consistently assigned to the same machine in the cluster, taking advantage of previously cached conversion output. But we are assuming you will provide us a value which is unique for the document which you are about to upload. If, instead, you simply use a hard-coded value for all documents, you will mistakenly force all work to a single machine in the cluster. Make sure this value is unique for the document you are about to upload!

    • markupId (String) The ID to use when querying markup with the XML and JSON layer APIs. If one isn't passed, we create one from the other information we're given. The markupId is required to have a non-zero length, should be less than 256 characters, and should consist of characters defined by RFC4648 - Base 64 Encoding with URL and Filename Safe Alphabet.
    • downloadName (String) Filename a browser should use when an end user downloads the source document (the filename of the Content-Disposition response header). We will use the displayName if this option is not provided.
    • fileExtension (String) A file extension that's used if the File Detection Service cannot determine what type of file was uploaded. We will get the extension from displayName if this option is not provided. This parameter only accepts alpha-numeric characters.
    • documentId (String) A customer supplied identifier which is used to uniquely identify a viewing package. The documentId is required to have a non-zero length less than 256 characters and must consist of characters defined by RFC4648 - Base 64 Encoding with URL and Filename Safe Alphabet. If a viewing package exists for the given documentId, PAS will use the content stored in that package and avoid sending any work to PrizmDoc Server. If a viewing package does not exist for the given documentId, PAS will ask PrizmDoc Server to immediately start preparing content for this viewing session and will also start creating a new viewing package in the background. If an errored viewing package exists for the given documentId, PAS will effectively ignore the documentId and ask PrizmDoc Server to dynamically prepare content for the viewing session.
    • packageType (String) When creating an on-demand viewing package, specify the type of packages to create for a document. The valid values are "full" or "pdf" and by default the value is "full". See POST /v2/viewingPackageCreators. "pdf" package types can only be created when the product is running with a metered license.

      NOTE: To use the "pdf" option, allowedClientFileFormats must also allow "pdf" as one of its options.

  • When using a URL for the source document:
    • type (String) Required. Set to url.
    • url (String) Required. URL to create a viewing session from.
    • headers (Object) Request headers to send from PrizmApplicationServices when retrieving the URL.
    • acceptBadSslCertificate (boolean) If true, allows the use of invalid SSL certificates. Default is false.
    • markupId (String) The ID to use when querying markup with the XML and JSON layer APIs. If one isn't passed, we create one from the other information we're given. The markupId is required to have a non-zero length, should be less than 256 characters, and should consist of characters defined by RFC4648 - Base 64 Encoding with URL and Filename Safe Alphabet.
    • downloadName (String) Filename a browser should use when an end user downloads the source document (the filename of the Content-Disposition response header). We will use the displayName if this option is not provided.
    • fileExtension (String) A file extension that's used if the File Detection Service cannot determine what type of file was uploaded. This parameter only accepts alpha-numeric characters.
    • documentId (String) A customer supplied identifier which is used to uniquely identify a viewing package. The documentId is required to have a non-zero length less than 256 characters and must consist of characters defined by RFC4648 - Base 64 Encoding with URL and Filename Safe Alphabet. If a viewing package exists for the given documentId, PAS will use the content stored in that package and avoid sending any work to PrizmDoc Server. If a viewing package does not exist for the given documentId, PAS will ask PrizmDoc Server to immediately start preparing content for this viewing session and will also start creating a new viewing package in the background. If an errored viewing package exists for the given documentId, PAS will effectively ignore the documentId and ask PrizmDoc Server to dynamically prepare content for the viewing session.
    • packageType (String) When creating an on-demand viewing package, specify the type of packages to create for a document. The valid values are "full" or "pdf" and by default the value is "full". See POST /v2/viewingPackageCreators. "pdf" package types can only be created when the product is running with a metered license.

      NOTE: To use the "pdf" option, allowedClientFileFormats must also allow "pdf" as one of its options.

  • When using a local file on the PAS server as the source document (self-hosted only, not recommended):
    • type (String) Required. Set to document.
    • fileName (String) Required. Filename that the Storage Provider API can use.
    • markupId (String) The ID to use when querying markup with the XML and JSON layer APIs. If one isn't passed, we create one from the other information we're given. The markupId is required to have a non-zero length, should be less than 256 characters, and should consist of characters defined by RFC4648 - Base 64 Encoding with URL and Filename Safe Alphabet.
    • downloadName (String) Filename a browser should use when an end user downloads the source document (the filename of the Content-Disposition response header). We will use the displayName if this option is not provided.
    • fileExtension (String) A file extension that's used if the File Detection Service cannot determine what type of file was uploaded. We will get the extension from fileName if this option is not provided. This parameter only accepts alpha-numeric characters.
    • documentId (String) A customer supplied identifier which is used to uniquely identify a viewing package. The documentId is required to have a non-zero length less than 256 characters and must consist of characters defined by RFC4648 - Base 64 Encoding with URL and Filename Safe Alphabet. If a viewing package exists for the given documentId, PAS will use the content stored in that package and avoid sending any work to PrizmDoc Server. If a viewing package does not exist for the given documentId, PAS will ask PrizmDoc Server to immediately start preparing content for this viewing session and will also start creating a new viewing package in the background. If an errored viewing package exists for the given documentId, PAS will effectively ignore the documentId and ask PrizmDoc Server to dynamically prepare content for the viewing session.
    • packageType (String) When creating an on-demand viewing package, specify the type of packages to create for a document. The valid values are "full" or "pdf" and by default the value is "full". See POST /v2/viewingPackageCreators. "pdf" package types can only be created when the product is running with a metered license.

      NOTE: To use the "pdf" option, allowedClientFileFormats must also allow "pdf" as one of its options.

  • When using a viewing package with pre-converted content:
    • type (String) Required. Set to viewingPackage.
    • documentId (String) Required. A customer supplied identifier which is used to uniquely identify a viewing package. The documentId is required to have a non-zero length less than 256 characters and must consist of characters defined by RFC4648 - Base 64 Encoding with URL and Filename Safe Alphabet. This value must refer to a completed viewing package, otherwise the viewing session will not be created and an error will be returned.
    • markupId (String) The ID to use when querying markup with the XML and JSON layer APIs. If one isn't passed, we create one from the other information we're given. The markupId is required to have a non-zero length, should be less than 256 characters, and should consist of characters defined by RFC4648 - Base 64 Encoding with URL and Filename Safe Alphabet.
    • downloadName (String) Filename a browser should use when an end user downloads the source document (the filename of the Content-Disposition response header). We will use the displayName if this option is not provided.
    • packageType (String) When creating an on-demand viewing package, specify the type of packages to create for a document. The valid values are "full" or "pdf" and by default the value is "full". See POST /v2/viewingPackageCreators. "pdf" package types can only be created when the product is running with a metered license.

      NOTE: To use the "pdf" option, allowedClientFileFormats must also allow "pdf" as one of its options.

  • When comparing two Microsoft Word documents:
    • type (String) Required. Set to comparison.
    • original (Object) Original document to compare.
      • When uploading the original document in a subsequent request: (NOTE: Use PUT /v2/viewingSessions/{viewingSessionId}/sourceFile/original and/or PUT /v2/viewingSessions/{viewingSessionId}/sourceFile/revised to upload the original and/or revised documents):
        • type (String) Required. Set to upload.
        • displayName (String) Required. Unique filename, including the extension, for the document that will be uploaded.
        • downloadName (String) Filename a browser should use when an end user downloads the original document (the filename of the Content-Disposition response header). We will use the displayName if this option is not provided.
        • fileExtension (String) A file extension that's used if the File Detection Service cannot determine what type of file was uploaded. This parameter only accepts alpha-numeric characters. We will get the extension from displayName if this option is not provided.
      • When using a URL for the original document:
        • type (String) Required. Set to url.
        • url (String) Required. URL to create a viewing session from.
        • headers (Object) Request headers to send from PrizmApplicationServices when retrieving the URL.
        • acceptBadSslCertificate (boolean) If true, allows the use of invalid SSL certificates. Default is false.

          NOTE: To use your own certificate authority, you need to specify an agent that was created with that CA as an option.

        • downloadName (String) Filename a browser should use when an end user downloads the original document (the filename of the Content-Disposition response header). We will use the displayName if this option is not provided.
        • fileExtension (String) A file extension that's used if the File Detection Service cannot determine what type of file was uploaded. This parameter only accepts alpha-numeric characters.
      • When using a local file on the PAS server as the original document (self-hosted only, not recommended):
        • type (String) Required. Set to document.
        • fileName (String) Required. Filename that the Storage Provider API can use.
        • downloadName (String) Filename a browser should use when an end user downloads the original document (the filename of the Content-Disposition response header). We will use the displayName if this option is not provided.
        • fileExtension (String) A file extension that's used if the File Detection Service cannot determine what type of file was uploaded. This parameter only accepts alpha-numeric characters. We will get the extension from fileName if this option is not provided.
    • revised (Object) Revised document to compare.
      • When uploading the revised document in a subsequent request: (NOTE: Use PUT /v2/viewingSessions/{viewingSessionId}/sourceFile/original and/or PUT /v2/viewingSessions/{viewingSessionId}/sourceFile/revised to upload the original and/or revised documents):
        • type (String) Required. Set to upload.
        • displayName (String) Required. Unique filename, including the extension, for the document that will be uploaded.
        • downloadName (String) Filename a browser should use when an end user downloads the revised document (the filename of the Content-Disposition response header). We will use the displayName if this option is not provided.
        • fileExtension (String) A file extension that's used if the File Detection Service cannot determine what type of file was uploaded. This parameter only accepts alpha-numeric characters. We will get the extension from displayName if this option is not provided.
      • When using a URL for the revised document:
        • type (String) Required. Set to url.
        • url (String) Required. URL to create a viewing session from.
        • headers (Object) Request headers to send from PrizmApplicationServices when retrieving the URL.
        • acceptBadSslCertificate (boolean) If true, allows the use of invalid SSL certificates. Default is false.

          NOTE: To use your own certificate authority, you need to specify an agent that was created with that CA as an option.

        • downloadName (String) Filename a browser should use when an end user downloads the revised document (the filename of the Content-Disposition response header). We will use the displayName if this option is not provided.
        • fileExtension (String) A file extension that's used if the File Detection Service cannot determine what type of file was uploaded. This parameter only accepts alpha-numeric characters.
      • When using a local file on the PAS server as the revised document (self-hosted only, not recommended):
        • type (String) Required. Set to document.
        • fileName (String) Required. Filename that the Storage Provider API can use.
        • downloadName (String) Filename a browser should use when an end user downloads the revised document (the filename of the Content-Disposition response header). We will use the displayName if this option is not provided.
        • fileExtension (String) A file extension that's used if the File Detection Service cannot determine what type of file was uploaded. This parameter only accepts alpha-numeric characters. We will get the extension from fileName if this option is not provided.
    • markupId (String) The ID to use when querying markup with the XML and JSON layer APIs. If one isn't passed, we create one from the other information we're given. The markupId is required to have a non-zero length, should be less than 256 characters, and should consist of characters defined by RFC4648 - Base 64 Encoding with URL and Filename Safe Alphabet.
    • downloadName (String) Filename a browser should use when an end user downloads the source document (the filename of the Content-Disposition response header). We will use the displayName if this option is not provided.
    • packageType (String) When creating an on-demand viewing package, specify the type of packages to create for a document. The valid values are "full" or "pdf" and by default the value is "full". See POST /v2/viewingPackageCreators. "pdf" package types can only be created when the product is running with a metered license.

      NOTE: To use the "pdf" option, allowedClientFileFormats must also allow "pdf" as one of its options.

• documentExtension (String) File extension of the source document (like "docx", "html", or "csv") used to indicate the source document file format. Often unnecessary. Only required when 1) the documentSource is "http" or "file" but the externalId containing the URL or file path did not end with a recognizable file extension and 2) the source document file format could not be automatically detected (this most-commonly occurs for text-based file formats, such as txt, csv, and html).

  NOTE: If Format Detection is disabled, then the source document format will never be automatically detected.

• password (String) Password to use when opening a password-protected source document.
• tenantId (String) Custom, arbitrary tenant id to be associated with the viewing session. PrizmDoc Server has no concept of tenants; if provided, this metadata is only for use by the calling application.
• origin (Object) Custom, arbitrary set of key/value string pairs to be associated with the viewing session. Intended for associating end user origin data (like IP address or hostname), but you can use any set of key/value strings you want.
• render (Object) Options which control how browser content is rendered:
  • html5 (Object) Options when the output format is HTML:
    • alwaysUseRaster (Boolean) Required. Determines whether only raster data, instead of SVG, should be created for the viewing session. With modern browsers, it is rare to only want raster. This is typically set to false. See the CAD Files topic for a use case when this option might be useful.
    • svgMaxImageSize (Number) The maximum edge length, in pixels, that is allowable for any image when creating SVG. For example, a value of 8000 would ensure that any images in a PDF whose width or height were greater than 8000 pixels would be down-sampled before the image was added to the final SVG. Default is configurable, but is typically 8000. To disable this optimization, use a value of 0.

      NOTE: When embedded images are very large and the optimization is disabled, browsers may display a placeholder icon instead of an image. If you want to keep high resolution images, consider setting this parameter to a large value, such as 30000, instead of setting it to 0.

    • vectorTolerance (Number) For CAD documents, the amount of path simplification that is allowable when creating the SVG. Path simplification will merge points which are "close together" to create optimized SVG. You can think of this value as defining what "close together" means. Higher values introduce more simplification but also more distortion. Default is configurable, but is typically 0.3. Cannot be greater than 10.0. To disable this optimization, use a value of 0.
• watermarks (Array of Objects) Objects describing watermarks which should be applied to page content. Each item must be an object which conforms to the following:
  • text watermark:
    • type: "text" (String) Required. Must be set to "text" to indicate the object represents a text watermark.
    • text (String) Actual text of the watermark. 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.
    • opacity (Number) Opacity of the watermark. 1.0 is completely opaque, 0.0 is completely transparent. Default is 1.0.
    • color (String) Text color. Can be any valid CSS color name (like "red") or hex value (like "#FF0000"). Default is "black".
    • fontFamily (String) Font family for the text. Default for SVG output is to use the browser's default font. Default for raster output is unspecified.
    • fontSize (String) Font size specified in points (like "12pt"). Default for SVG output is to use the browser's default font size. Default for raster output is unspecified.
    • fontWeight (String) Determines the font weight. Possible values:
      • "normal" (default)
      • "bold"
    • textDecoration (String) Possible values:
      • "none" (default)
      • "underlined"
    • horizontalAlign (String) Determines the horizontal position of the watermark. Default is "center". Possible values:
      • "left" Text will be horizontally anchored to the left side of the page and text will be left aligned.
      • "center" Text will be horizontally anchored to the center of the page and text will be centered. (default)
      • "right" Text will be horizontally anchored to the right side of the page and text will be right aligned.
    • verticalAlign (String) Determines the vertical position of the watermark. Default is "middle". Possible values:
      • "top" Text will be vertically anchored to the top of the page.
      • "middle" Text will be vertically anchored to the middle of the page. (default)
      • "bottom" Text will be vertically anchored to the bottom of the page.
  • diagonal text watermark:
    • type: "diagonalText" (String) Required. Must be set to "diagonalText" to indicate the object represents a diagonal text watermark.
    • text (String) Actual text of the watermark. 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.
    • opacity (Number) Opacity of the watermark. 1.0 is completely opaque, 0.0 is completely transparent. Default is 1.0.
    • color (String) Text color. Can be any valid CSS color name (like "red") or hex value (like "#FF0000"). Default is "black".
    • fontFamily (String) Font family for the text. Default for SVG output is to use the browser's default font. Default for raster output is unspecified.
    • fontSize (String) Font size specified in points (like "12pt"). Default for SVG output is to use the browser's default font size. Default for raster output is unspecified.
    • fontWeight (String) Determines the font weight. Possible values:
      • "normal" (default)
      • "bold"
    • textDecoration (String) Possible values:
      • "none" (default)
      • "underlined"
    • slope (String) Controls the text angle. Default is "up". Possible values:
      • "up" Text will start in the lower-left corner of the page and extend upwards to the upper-right corner of the page. (default)
      • "down" Text will start in the upper-left corner of the page and extend downwards to the lower-right corner of the page.
  • image watermark:
    • type: "image" (String) Required. Must be set to "image" to indicate the object represents an image watermark.
    • opacity (Number) Opacity of the watermark. 1.0 is completely opaque, 0.0 is completely transparent. Default is 1.0.
    • src (String) Required. URL or work file id of a PNG image to use for this watermark. When using a URL, the URL must be accessible from the server where PrizmDoc Server is running.

      NOTE: The src MUST be a PNG. If you use a different image format, invalid watermarks will be created.

    • horizontalAlign (String) Determines the horizontal position of the watermark. Default is "center". Possible values:
      • "left" Image will be horizontally anchored near the left side of the page.
      • "center" Image will be horizontally anchored to the center of the page. (default)
      • "right" Image will be horizontally anchored near the right side of the page.
    • verticalAlign (String) Determines the vertical position of the watermark. Default is "middle". Possible values:
      • "top" Image will be vertically anchored near the top of the page.
      • "middle" Image will be vertically anchored to the middle of the page. (default)
      • "bottom" Image will be vertically anchored near the bottom of the page.
    • scale (Number) Determines the relative size of the image as compared to the size of the page. Value must be between 0.0 and 1.0. A value of 1.0 indicates the image will be scaled to the size of the page while 0.0 indicates the image will be scaled infinitesimally small and will not be rendered. Default is 0.25.
    • autoSize (String) When set, the image will be automatically sized to fill the page (any value provided for scale, horizontalAlign, and verticalAlign will be ignored). Possible values:
      • "fit" Image will be scaled to be as large as possible while still completely fitting within the page. The aspect ratio of the image is maintained.
      • "fill" Image will be scaled to be large enough that the entire page is covered by the image. Some of the image may fall off the edge of the page, but the entire page is guaranteed to be covered by some part of the image. The aspect ratio of the image is maintained.
      • "stretch" Image width and height will be independently resized so that the image width and height are the same as the page. The aspect ratio of the image is ignored.
• pageContentEncryption (String) Controls whether or not page content will be encrypted for the viewing session. See the Enabling Content Encryption topic for more information about this feature. Possible values:
  • "default" Product configuration will be used to determine whether or not page content will be encrypted (see viewing.contentEncryption.enabled in the Central Configuration file).
  • "enabled" Page content will be encrypted for the viewing session.
  • "disabled" Page content will not be encrypted for the viewing session.
• countOfInitialPages (Integer) Number of pages which should be immediately pre-converted, or 0 if all pages should be immediately pre-converted. Default is 0.
• startConverting (String) When the documentSource is "http" or "file", controls whether initial pages should be converted as soon as the document has been acquired. Default is "none". Possible values:
  • "none" Conversion will begin only after the session is explicitly started or page content or attributes are requested. (default)
  • "initialPages" Conversion will begin as soon as the source document has been acquired, unless the document format is one of the file formats provided in the allowedClientFileFormats property.
• allowedClientFileFormats (Array of Strings) This property defines the file formats that will be used for client-side viewing. When defined, a viewing session's source document will not trigger processing of the document. Consequently, the HTML5 Viewing and Search Tasks APIs will be disabled for that viewing session. Additionally, when this property is defined, the GET /v2/viewingSessions/{viewingSessionId}/clientFile route will return the document in one of the specified allowed formats. Currently, the only allowed client file format is "pdf". This property is required and must include "pdf" when source.packageType is set to "pdf". This property is used for hybrid viewing and can only be used when the product is running with a metered license.
• contentType (String) Determines what kind of browser content will be immediately pre-generated (other kinds of content may still be generated if explicitly requested). Possible values:
  • "svgb" Pre-generate fully-optimized SVG (uses a unicode inline font to store glyph definitions). Smallest possible SVG, but may not be compatible with some browsers. Recommended whenever possible.
  • "svga" Pre-generate partially-optimized SVG (uses a non-unicode inline font to store only the most frequently-occurring glyph definitions). May not be compatible with some browsers. Use only if "svgb" content is not compatible with the target browser.
  • "svg" Pre-generate unoptimized SVG (no font is used; glyph definitions are expressed as SVG path operations). Broadest compatibility with browsers but typically much larger, so it renders and scrolls much slower than "svgb" and "svga". Not recommended. Use only as a fallback if both svgb and svga are not compatible with the target browser, or the use of webfonts is disabled in the target browser.
  • "png" Pre-generate raster content.
• serverCaching (String) Controls whether output is kept for potential reuse by other viewing sessions. Default is "full". Possible values:
  • "full" Output will be written to disk on the server and retained for reuse by other viewing sessions created for the same source document. Output will not be deleted until the configured viewing cache lifetime is reached (which is a full day with an out-of-box configuration; see viewing.cacheLifetime in Central Configuration). Saves processing time if a source document is viewed repeatedly before the cached data is deleted, but does consume more disk space. (default)
  • "none" Output will be written to disk on the server but only retained for the duration of the viewing session and never shared with other viewing sessions. Once the viewing session expires, the output will be deleted from the disk. Saves disk space if you know that it is unlikely a source document will ever be viewed more than once, but can result in redundant processing if the same source document is viewed repeatedly.
• serverSideSearch (String) Determines whether the server-side search feature will be available for the viewing session. Default is "enabled". Possible values:
  • "enabled" Server-side search will be available for the viewing session. (default)
  • "disabled" Server-side search will not be available for the viewing session.
• attachmentIndex (Integer) Intended for use only by PrizmDoc Server when it automatically creates viewing sessions for attachments. This is not a property your application should use. If the source document is an attachment that belongs to another document (such as an email or PDF Portfolio), the 1-based index of this attachment in the list of all attachments (e.g. 1 means it was the first attachment, 2 means it was the second, etc.) or 0 to indicate that the source document is not an attachment. Default is 0.
• attachmentDisplayName (String) Intended for use only by PrizmDoc Server when it automatically creates viewing sessions for attachments. This is not a property your application should use. If the source document is an attachment that belongs to another document (such as an email or PDF Portfolio), the filename of the attachment or null. Default is null.

Successful Response

Response Body

JSON with metadata about the created viewing session.

• viewingSessionId (String) Unique id for this viewing session.

Error Responses

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"
    }
}

NOTE: See the Base URL for PAS topic for more information.

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
    }
}

NOTE: See the Base URL for PAS topic for more information.

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"
    }
}

NOTE: See the Base URL for PAS topic for more information.

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"
    }
}

NOTE: See the Base URL for PAS topic for more information.

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",
        "displayName": "2019-10-07-comparison.docx", //required
        "original": {
            "type": "upload",
            "displayName": "2019-10-07-original.docx" //optional
        },
        "revised": {
            "type": "upload",
            "displayName": "2019-10-07-revised.docx" //optional
        }
    }
}

NOTE: See the Base URL for PAS topic for more information.

PUT /ViewingSession/u{viewingSessionId}/SourceFile

Routes key: PutViewingSessionSourceFile

Uploads a document to the session.

Request

Request Headers

Request Body

The bytes of the source document.

Successful Response

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

Error Responses

Example

Request

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

<<file bytes>>

NOTE: See the Base URL for PAS topic for more information.

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

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

Example

Request

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

<<file bytes>>

NOTE: See the Base URL for PAS topic for more information.

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

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

Example

Request

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

<<file bytes>>

NOTE: See the Base URL for PAS topic for more information.

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

Response Headers

Response Body

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

Example

Request

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

NOTE: See the Base URL for PAS topic for more information.

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

Response Headers

Response Body

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

Error Responses

Example

Request

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

NOTE: See the Base URL for PAS topic for more information.

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

Response Headers

Response Body

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

Error Responses

Example

Request

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

NOTE: See the Base URL for PAS topic for more information.

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

Successful Response

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

• delayEnabled (Boolean) - Indicates whether the server has enforced an artificial delay before the document conversion results are allowed to be delivered to the viewer.
• delaySecondsRemaining (Integer) The number of seconds remaining in the artificially-imposed delay before the document conversion results are allowed to be delivered to the viewer. Only present when delayEnabled is true.
• downloadDisabled (Boolean) Indicates whether downloading of the source document has been disabled for this viewing session.
• markupSavingDisabled (Boolean) Indicates whether saving markup has been disabled for this viewing session.
• markupLoadingDisabled (Boolean) Indicates whether loading markup has been disabled for this viewing session.
• contentConvertersDisabled (Boolean) Indicates whether the content converters feature has been disabled for this viewing session.
• markupBurnersDisabled (Boolean) Indicates whether the markup burner feature has been disabled for this viewing session.
• formExtractorsDisabled (Boolean) Indicates whether the forms extractors feature has been disabled for this viewing session.
• formInfoDisabled (Boolean) Indicates whether the form detection feature has been disabled for this viewing session.

Example Responses

When the product is licensed, valid allowedClientFileFormats is provided, 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,
  "clientFileRetrievalDisabled": 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
}

When the product is licensed, valid allowedClientFileFormats is not supplied, 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,
  "clientFileRetrievalDisabled": 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

Request Body

• password (String) Password to use when opening a password-protected source document. If the parameter is not provided a new viewing session is created with a default null password parameter value.

URL Parameters

Successful Response

Response Body

JSON with metadata about the created viewing session.

• viewingSessionId (String) Unique id for this viewing session.

Error Responses

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

Example

Request

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

{
    "password":"123"
}

NOTE: See the Base URL for PAS topic for more information.

Response

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

{
    "viewingSessionId": "THMMytF4ACHrxmN2bXj4vahx4Gnwly_kEeFt20XtRau-z43pPHIjUy5JXJ05Wj1MaqvdfsXp98JxIk7ALWkukg"
}

GET /v2/viewingSessions/{viewingSessionId}/clientFile

Gets the source document of the viewing session for client-side viewing. This route can only be used when the product is running with a metered license.

Request

URL Parameters

Response Headers

Response Body

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

Examples

Request

GET prizmdoc_server_base_url/v2/viewingSessions/uXYZ.../clientFile?accept=pdf

Successful Response

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

<<file bytes>>

Error response when the feature is not licensed

480 FeatureNotLicensed
Content-Type: application/json

{
  "errorCode": "FeatureNotLicensed"
}

Error response when the feature is not turned on

480 DocumentFormatNotAllowed
Content-Type: application/json

{
  "errorCode": "DocumentFormatNotAllowed"
}

Error response when the accept query parameter is not in the array of allowedClientFileFormats (i.e. a docx client file is requested but allowedClientFormats = ["pdf"]).

480 DocumentUnavailable
Content-Type: application/json

{
  "errorCode": "DocumentUnavailable"
}

Error response when the "accept" parameter is missing

480 MissingInput
Content-Type: application/json

{
  "errorCode": "MissingInput",
  "errorDetails": {
    "in": "query",
    "at": "accept",
    "expected": {
      "flags": ["pdf"]
    }
  }
}