Introduction

The markup burners REST API allows your application to “burn” markup into a document, producing a new PDF with annotations applied.

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 markup burning and redaction with the.NET SDK.

Secure Redactions

The best way to ensure a completely secure redaction is to "flatten" the document after applying the redaction. You can do this by converting the document to a raster format (TIFF is recommended for PDF conversion) using PrizmDoc's Content Conversion Service, and then converting it back to PDF format. This will result in a PDF with a single layer and no hidden objects, meaning there is no way to remove the redaction or reveal hidden information after doing this. Note that this will usually lower the quality and increase the file size of PDFs that are largely text. The following workflow shows you how to use the Content Conversion Service API to create secure redactions and also make the PDF searchable.

Available URLs

POST /PCCIS/V1/MarkupBurner

Creates and starts a new MarkupBurner.

NOTE: CAD files are not supported.

NOTE: When applying redactions, the MarkupBurner removes PDF annotations when a markup redaction rectangle intersects it's rectangle. Also, the MarkupBurner removes AcroForm fields when the redaction rectangle and the AcroForm's rectangle intersection area is more than 40% for the annotation rectangle or for the redaction rectangle.

NOTE: There are limitations on what content is removed under the rectangle redaction box on vector content in PDF files when the markup burner burns the redactions.

• When redacting a vector line, a small portion of the lines under the redaction box may still exist under the redaction.
• When redacting a vector graphic with color filling, such as a colored in half circle, the color will still remain under the redaction rectangle.
• When redacting a vector graphic rectangle, they are fully removed only if the PDF graphic rectangle is fully overlapped by the redaction rectangle. If they are partially overlapped then the part not overlapped remains unredacted.

A MarkupBurner represents a process that runs on the server to "burn" markup into a document. The "burning" process makes the markup definitions a permanent part of a document. The server process is started by this request then a response is sent. Use the GET /PCCIS/V1/MarkupBurner/{processId} URL below to get the status and results of an in-progress or completed MarkupBurner process.

The input required to create a MarkupBurner is two WorkFile objects; one representing the JSON or XML which defines the markup to burn, the other representing the source document on which to burn the markup. Refer to the work file API topic for more information.

A new document is created that contains the burned-in markup. The source document will not be modified. The new document will be made available by a new WorkFile ID.

By default, MarkupBurner objects will be automatically deleted 20 minutes after they are created.

Request

Request Headers

Request Body

In the request body, provide JSON containing the following properties:

• input (Object) Input to create the MarkupBurner.

  • documentFileId (String) Required. The ID of the WorkFile that represents the document to burn in the markup. This document will not be modified.

  • redactionOptions (Object) Redaction options. May contain:

    • mode (String) How redactions should be applied. May be one of the following:

      • "normal" - Actually redact the document, removing document content covered by redactions, drawing opaque redaction rectangles, and drawing any associated redaction reason text in the center of the rectangles.

      • "draft" - Do NOT actually redact the document. Instead, indicate which parts of the document would be redacted by drawing partially transparent redaction rectangles over the parts of the document that would be redacted. In order to avoid interfering with the original document content, the redaction reason text will be transparent in the center of the transparent redaction rectangles.

        Default is "normal".

    • sharedImages (String) Controls redaction of images shared across multiple pages in a document. Shared images are normally used to display the same background or a logo across the document. May be one of the following:

      • "redact" - Redact shared images by removing the content of an image covered by redactions, drawing opaque redaction rectangles, and drawing any associated redaction reason text in the center of the rectangles. Redacting a shared image on one page will result in this image shown as redacted on all pages of a document.

      • "preserve" - Preserve shared images intact, but draw opaque redaction rectangles over them, and draw any associated redaction reason text in the center of the rectangles. Preserving a shared image on one page will result in this image shown intact on all other pages of a document.

        Default is "redact".

    • draftOptions (Object) Options to apply when mode is set to "draft" (ignored otherwise). May contain:
      • opacity (number) Controls the opacity of redactions when input.redactionOptions.mode is set to "draft". Must be a value between 0 and 1 where 0 is fully transparent and 1 is fully opaque. Default is 0.2.
      • textOpacity (number) Controls the opacity of redactions reason text when input.redactionOptions.mode is set to "draft". Must be a value between 0 and 1 where 0 is fully transparent and 1 is fully opaque. Default is 0.8.

    • bookmarks (String) Controls the new document PDF bookmarks when markup is applied. May be one of the following:

      • "preserve" - Preserve the source document PDF bookmarks for the new PDF document.

      • "removeAll" - Remove all PDF bookmarks from the new PDF document.

        Default is "preserve".

    • comments (String) Controls the new document comments and associated PDF annotations when markup is applied. May be one of the following:

      • "preserve" - Preserve the source document PDF comments for the new PDF document.

      • "removeHidden" - Remove all PDF comments, which are hidden and not available in the PrizmDoc Viewer from the new PDF document.

        Default is "preserve".

    • includeCategories (Array of String) When present, limits the burning to only include the specified categories of mark types. The following categories are available:

      • "annotations"
      • "redactions"

      • "signatures"

        For example, if you only want to apply redactions you could specify:

        "includeCategories": ["redactions"]

        Or, if you only wanted to apply annotations and signatures you could specify:

        "includeCategories": ["annotations", "signatures"]

  • markupFileId (String) Required. The ID of the WorkFile that represents the JSON or XML document which contains the markup definition.
  • minSecondsAvailable (Integer) The minimum number of seconds which this MarkupBurner must remain available. The default lifetime is defined by the processIds.lifetime central configuration parameter. This value is ignored if it is shorter than the default value.

Successful Response

Response Body

If successful, this method returns JSON containing the following properties:

• input (Object) Input we accepted to create the MarkupBurner.
  • documentFileId (String) The ID of the WorkFile that represents the document to burn in the markup. This document will not be modified. This is an echo of what was passed in by the request.
  • markupFileId (String) The ID of the WorkFile that represents the JSON or XML document which contains the markup definition. This is an echo of what was passed in by the request.
• expirationDateTime (String) The date and time (in ISO 8601 Extended Format) when the MarkupBurner will be deleted.
• processId (String) The ID of the MarkupBurner.
• state (String) The current state of the markup burning process running on the server. This will always be "processing" in this response.
• percentComplete (Integer) The percentage (0 – 100) complete of the markup burning process. This will always be 0 in this response.
• errorCode (String) An error code string if a problem occurred during the markup burning process. This will always be null in this response.
• output (Object)
  • documentFileId (String) The ID of the new WorkFile that represents a new document with markup burned into it. This will always be null in this response.
• affinityToken (String) Affinity token for this search context. Present when clustering is enabled.

Error Responses

Examples

Creating a MarkupBurner

Request

POST prizmdoc_server_base_url/PCCIS/V1/MarkupBurner
Content-Type: application/json
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

{
    "input": {
        "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ",
        "markupFileId": "aQ1BdViqmUisBuevJKO9Sw"
    },
    "minSecondsAvailable": 60
}

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

Response

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

{
    "input": {
        "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ",
        "markupFileId": "aQ1BdViqmUisBuevJKO9Sw"
    },
    "expirationDateTime": "2014-12-17T20:38:39.796Z",
    "processId": "ElkNzWtrUJp4rXI5YnLUgw",
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
    "state": "processing",
    "percentComplete": 0,
    "errorCode": null,
    "output": null
}

GET /PCCIS/V1/MarkupBurner/{processId}

Gets the status and result of an existing MarkupBurner.

Requests can be sent to this URL repeatedly while state is "processing".

When state is "complete", the new document with burned-in annotations will be made available by a new WorkFile ID in the output.documentFileId. Refer to the work file API topic to find out how to download a WorkFile.

If the markup burning process encountered an error, the state property will be "error", the errorCode property will contain an error code string and output will be null.

Request

Request Headers

URL Parameters

Response Body

If successful, this method returns JSON containing the following properties:

• input (Object) Input we accepted to create the MarkupBurner.
  • documentFileId (String) The ID of the WorkFile that represents the document to burn in the markup. This document will not be modified.
  • markupFileId (String) The ID of the WorkFile that represents the XML document which contains the markup definition.
• expirationDateTime (String) The date and time (in ISO 8601 Extended Format) when the MarkupBurner will be deleted.
• processId (String) The ID of the MarkupBurner.
• state (String) The current state of the markup burning process running on the server. The following values are allowed:
  • "processing" - The markup burning is in progress.
  • "complete" - The markup burning is completed.
  • "error" - The markup burning returns an error.
• percentComplete (Integer) The percentage (0 – 100) complete of the markup burning process.
• errorCode (String) An error code string if a problem occurred during the markup burning process.
• output (Object)
  • documentFileId (String) The ID of the new WorkFile that represents a new document with markup burned into it.
• affinityToken (String) Affinity token for this search context. Present when clustering is enabled.

Error Responses

Examples

Request

GET prizmdoc_server_base_url/PCCIS/V1/MarkupBurner/ElkNzWtrUJp4rXI5YnLUgw
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

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

Response when the state is "processing"

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

{
    "input": {
        "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ",
        "markupFileId": "aQ1BdViqmUisBuevJKO9Sw"
    },
    "expirationDateTime": "2014-12-17T20:38:39.796Z",
    "processId": "ElkNzWtrUJp4rXI5YnLUgw",
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
    "state": "processing",
    "percentComplete": 100,
    "errorCode": null,
    "output": null
}

Response when the state is "complete"

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

{
    "input": {
        "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ",
        "markupFileId": "aQ1BdViqmUisBuevJKO9Sw"
    },
    "expirationDateTime": "2014-12-17T20:38:39.796Z",
    "processId": "ElkNzWtrUJp4rXI5YnLUgw",
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
    "state": "complete",
    "percentComplete": 100,
    "errorCode": null,
    "output": {
        "documentFileId": "vry3FPE0zQqYwhzndRccOQ"
    }
}

Response when the state is "error" because the work file that represents document to burn could not be found

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

{
    "input": {
        "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ",
        "markupFileId": "aQ1BdViqmUisBuevJKO9Sw"
    },
    "expirationDateTime": "2014-12-17T20:38:39.796Z",
    "processId": "ElkNzWtrUJp4rXI5YnLUgw",
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
    "state": "error",
    "percentComplete": 0,
    "errorCode": "DocumentFileIdDoesNotExist"
}

Response when the state is "error" because the work file that contains markup could not be found

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

{
    "input": {
        "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ",
        "markupFileId": "aQ1BdViqmUisBuevJKO9Sw"
    },
    "expirationDateTime": "2014-12-17T20:38:39.796Z",
    "processId": "ElkNzWtrUJp4rXI5YnLUgw",
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
    "state": "error",
    "percentComplete": 0,
    "errorCode": "MarkupFileIdDoesNotExist"
}

Response when the state is "error" because the markup work file does not contain valid XML markup and the extension of the markup work file is not JSON

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

{
    "input": {
      "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ",
      "markupFileId": "aQ1BdViqmUisBuevJKO9Sw"
  },
  "expirationDateTime": "2014-12-17T20:38:39.796Z",
  "processId": "ElkNzWtrUJp4rXI5YnLUgw",
  "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
  "state": "error",
  "percentComplete": 0,
  "errorCode": "RedactionError"
}

Response when the state is "error" because the work file that contains markup JSON cannot be parsed as JSON

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

{
    "input": {
      "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ",
      "markupFileId": "aQ1BdViqmUisBuevJKO9Sw"
  },
  "expirationDateTime": "2014-12-17T20:38:39.796Z",
  "processId": "ElkNzWtrUJp4rXI5YnLUgw",
  "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
  "state": "error",
  "percentComplete": 0,
  "errorCode": "InvalidJson"
}

Response when the state is "error" because the work file that contains markup JSON does not match the JSON Marks Schema

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

{
    "input": {
      "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ",
      "markupFileId": "aQ1BdViqmUisBuevJKO9Sw"
  },
  "expirationDateTime": "2014-12-17T20:38:39.796Z",
  "processId": "ElkNzWtrUJp4rXI5YnLUgw",
  "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
  "state": "error",
  "percentComplete": 0,
  "errorCode": "InvalidMarkup"
}

POST /PCCIS/V1/ViewingSession/u{viewingSessionId}/MarkupBurner

Starts a new MarkupBurner using the source document of a viewing session and a provided markup data as input. When the asynchronous process is ultimately finished, the output will be a new document which includes the provided markup as part of the document itself (the original source document of the viewing session is left unaltered).

This is a specialized URL which allows you to do markup burning against the source file of an existing viewing session without needing to use the work file API.

This request merely begins the markup burning process. Once started, you poll the status of the process using the GET /PCCIS/V1/ViewingSession/u{viewingSessionId}/MarkupBurner/{processId} URL below to know when the process has completed.

Request

Request Headers

URL Parameters

Query String Parameters

Request Body

The JSON or XML markup to burn into the source document.

Response Body

If successful, a JSON object which may contain:

• processId (String) The id of the process.
• state (String) The current state of the markup burning process running on the server. This will always be "processing" in the initial POST response.
• percentComplete (Integer) The percentage (0 – 100) complete of the process. This will always be 0 in the initial POST response.
• input (null) Legacy property which exists only for backwards compatibility. Value will always be null. DEPRECATION NOTICE: This Legacy property has been deprecated and will be removed in a future release.
• output (null) Legacy property which exists only for backwards compatibility. Value will always be null. DEPRECATION NOTICE: This Legacy property has been deprecated and will be removed in a future release.

Error Responses

Examples

Request to burn a rectangle annotation using JSON markup

POST prizmdoc_server_base_url/PCCIS/V1/ViewingSession/uDLbVh9sTmXJAmd1GeXbS9Gn3WHxs8oib2xPsW2xEFjnIDdoJcudPtxciodSYFQq6zYGabQ_rJIecdbkImTTkSA/MarkupBurner
Content-Type: application/json
{
  "marks": [
    {
      "uid": "Z2diOV8yMDE3LTAzLTMxVDA3OjQ5OjExLjUyNVpfY2VnNjZy",
      "interactionMode": "Full",
      "pageNumber": 1,
      "type": "RectangleAnnotation",
      "creationDateTime": "2017-03-31T07:49:11.525Z",
      "modificationDateTime": "2017-03-31T07:49:11.526Z",
      "data": {},
      "conversation": {},
      "rectangle": {
        "x": 0,
        "y": 0,
        "width": 0,
        "height": 0
      },
      "pageData": {
        "width": 612,
        "height": 792
      },
      "borderColor": "#000000",
      "borderThickness": 4,
      "fillColor": "#FB0404",
      "opacity": 255
    }
  ]
}

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

Request to burn a rectangle annotation using JSON markup with removal of acroform fields

POST prizmdoc_server_base_url/PCCIS/V1/ViewingSession/uDLbVh9sTmXJAmd1GeXbS9Gn3WHxs8oib2xPsW2xEFjnIDdoJcudPtxciodSYFQq6zYGabQ_rJIecdbkImTTkSA/MarkupBurner?RemoveFormFields=acroform
Content-Type: application/json
{
  "marks": [
    {
      "uid": "Z2diOV8yMDE3LTAzLTMxVDA3OjQ5OjExLjUyNVpfY2VnNjZy",
      "interactionMode": "Full",
      "pageNumber": 1,
      "type": "RectangleAnnotation",
      "creationDateTime": "2017-03-31T07:49:11.525Z",
      "modificationDateTime": "2017-03-31T07:49:11.526Z",
      "data": {},
      "conversation": {},
      "rectangle": {
        "x": 0,
        "y": 0,
        "width": 0,
        "height": 0
      },
      "pageData": {
        "width": 612,
        "height": 792
      },
      "borderColor": "#000000",
      "borderThickness": 4,
      "fillColor": "#FB0404",
      "opacity": 255
    }
  ]
}

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

Response

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

{
    "input": null,
    "processId": "ElkNzWtrUJp4rXI5YnLUgw",
    "state": "processing",
    "percentComplete": 0,
    "errorCode": null,
    "output": null
}

GET /PCCIS/V1/ViewingSession/u{viewingSessionId}/MarkupBurner/{processId}

Gets the status of a MarkupBurner for a viewing session.

Requests are typically sent to this URL repeatedly as long as the state is "processing".

When state is "complete", a new document with the provided markup burned into it will be available at:

GET /PCCIS/V1/ViewingSession/u{viewingSessionId}/MarkupBurner/{processId}/Document

If an error occurred and the output could not be created, the state property will be "error" and the errorCode property will contain an error code string.

Request

URL Parameters

Response Body

If successful, a JSON object which may contain:

• processId (String) The id of the process.
• state (String) The current state of the process. The following values are allowed:
  • "processing" - The markup burning is in progress.
  • "complete" - The markup burning is completed.
  • "error" - The markup burning returns an error.
• percentComplete (Integer) The percentage (0 – 100) complete of the process.
• errorCode (String) An error code string if a problem occurred during processing.
• input (null) Legacy property which exists only for backwards compatibility. Value will always be null. DEPRECATION NOTICE: This Legacy property has been deprecated and will be removed in a future release.
• output (null) Legacy property which exists only for backwards compatibility. Value will always be null. DEPRECATION NOTICE: This Legacy property has been deprecated and will be removed in a future release.

Error Responses

Examples

Request

GET prizmdoc_server_base_url/PCCIS/V1/ViewingSession/uDLbVh9sTmXJAmd1GeXbS9Gn3WHxs8oib2xPsW2xEFjnIDdoJcudPtxciodSYFQq6zYGabQ_rJIecdbkImTTkSA/MarkupBurner/5rGUUh3Qxhf6VXm8RkBPfA

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

Response when the state is "processing"

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

{
    "input": null,
    "processId": "5rGUUh3Qxhf6VXm8RkBPfA",
    "state": "processing",
    "percentComplete": 0,
    "errorCode": null,
    "output": null
}

Response when the state is "complete"

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

{
    "input": null,
    "processId": "5rGUUh3Qxhf6VXm8RkBPfA",
    "state": "complete",
    "percentComplete": 100,
    "errorCode": null,
    "output": null
}

Response when the state is "error" because the provided markup XML did not contain valid XML markup or the provided markup JSON was auto-detected as a non-text format

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

{
    "input": null,
    "processId": "53LCkvO8-rsDIaW95WgoFA",
    "state": "error",
    "percentComplete": 0,
    "errorCode": "RedactionError",
    "output": null
}

Response when the state is "error" because the provided markup JSON cannot be parsed as JSON

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

{
    "input": null,
    "processId": "53LCkvO8-rsDIaW95WgoFA",
    "state": "error",
    "percentComplete": 0,
    "errorCode": "InvalidJson",
    "output": null
}

Response when the state is "error" because the provided markup JSON does not match the JSON Marks Schema

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

{
    "input": null,
    "processId": "53LCkvO8-rsDIaW95WgoFA",
    "state": "error",
    "percentComplete": 0,
    "errorCode": "InvalidMarkup",
    "output": null
}

GET /PCCIS/V1/ViewingSession/u{viewingSessionId}/MarkupBurner/{processId}/Document?ContentDispositionFilename={ContentDispositionFilename}

Gets the output result of a MarkupBurner process for a viewing session.

Request

URL Parameters

Response Headers

Response Body

The raw bytes of the PDF document with markup burned into it.

Error Responses

Examples

Request

GET prizmdoc_server_base_url/PCCIS/V1/ViewingSession/uDLbVh9sTmXJAmd1GeXbS9Gn3WHxs8oib2xPsW2xEFjnIDdoJcudPtxciodSYFQq6zYGabQ_rJIecdbkImTTkSA/MarkupBurner/ElkNzWtrUJp4rXI5YnLUgw/Document

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

Response

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="Greek____.pdf"; filename*=UTF-8''Greek%CE%91%CE%92%CE%93%CE%94.pdf


<<PDF data>>