PrizmDoc Viewer v13.12 Release - Updated
API Reference / PrizmDoc Server REST API / Application Development / Markup Burners
In This Topic
    Markup Burners
    In This Topic

    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.

    Available URLs

    URL Description
    POST /PCCIS/V1/MarkupBurner Creates and starts a new MarkupBurner.
    GET /PCCIS/V1/MarkupBurner/{processId} Gets the status and result of an existing MarkupBurner.
    POST /PCCIS/V1/ViewingSession/u{viewingSessionId}/MarkupBurner Starts a new MarkupBurner using the source document of a viewing session and provided markup data as input.
    GET /PCCIS/V1/ViewingSession/u{viewingSessionId}/MarkupBurner/{processId} Gets the status of a MarkupBurner for a viewing session.
    GET /PCCIS/V1/ViewingSession/u{viewingSessionId}/MarkupBurner/{processId}/Document Gets the output result of a MarkupBurner process for a viewing session.

    POST /PCCIS/V1/MarkupBurner

    Creates and starts a new MarkupBurner.

    NOTE: CAD files are not supported.

    NOTE: When applying redactions, PDF annotations are never removed.

    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

    Name Description
    Content-Type Must be application/json
    Accusoft-Affinity-Token The affinityToken of the work files specified by input.documentFileId and input.markupFileId. Required when server clustering is enabled.

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

    Status Code Description
    400 Bad Request, if input.documentFileId, input.markupFileId is missing or invalid format, or if minSecondsAvailable is not a number.
    405 Method Not Allowed, if POST HTTP method is not used.
    480 with JSON errorCode "LicenseCouldNotBeVerified". The server's license could not be verified. If you are evaluating the product without a license, the product is running in evaluation mode and this particular part of the product is unavailable without a license. If you have a license, make sure you configured your license correctly, that your license has not expired, and that you have not exceeded any license limits (such as, for a cloud license, the total number of logical CPU cores in use).

    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
    }
    

    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

    Name Description
    Content-Type Must be application/json
    Accusoft-Affinity-Token The affinityToken of the work files specified by input.documentFileId and input.markupFileId. Required when server clustering is enabled.

    URL Parameters

    Parameter Description
    {processId} The id of the process.

    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

    Status Code Description
    404 Not Found, if {processId} does not exist.
    405 Method Not Allowed, if GET HTTP method is not used.

    Examples

    Request

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

    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

    Name Description
    Content-Type Specifies the type of content being provided to the markup burner process. It must be application/xml or application/json depending on the markup format used in the request body.

    URL Parameters

    Parameter Description
    {viewingSessionId} The id provided in the response from POST /PCCIS/V1/ViewingSession.

    Query String Parameters

    Parameter Description
    {RemoveFormFields} Optional parameter indicating which interactive form fields to remove from the source document upon markup burner process. Currently only 'acroform' value is supported. Please see example below.

    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.
    • output (null) Legacy property which exists only for backwards compatibility. Value will always be null.

    Error Responses

    Status Code Description
    404 Not Found, if {viewingSessionId} does not exist.
    405 Method Not Allowed, if POST HTTP method is not used.

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

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

    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

    Parameter Description
    {viewingSessionId} The id provided in the response from POST /ViewingSession.
    {processId} The id of the process.

    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.
    • output (null) Legacy property which exists only for backwards compatibility. Value will always be null.

    Error Responses

    Status Code Description
    404 Not Found, if either the {viewingSessionId} or {processId} do not exist.
    405 Method Not Allowed, if GET method is not used.

    Examples

    Request

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

    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

    Parameter Description
    {viewingSessionId} The id provided in the response from POST /ViewingSession.
    {processId} The id of the process which identifies the MarkupBurner task as a string.
    {ContentDispositionFilename} The filename as a URL-encoded string, without extension, to be used in the Content-Disposition response header (the file extension will be appended automatically). The default value is "document".

    Response Headers

    Name Description
    Content-Disposition Specifies 'attachment' disposition, RFC-2183 compatible filename parameter and an RFC-8187 compatible filename* parameter, allowing the use of non-ASCII filenames.
    Content-Type Will be application/pdf.

    Response Body

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

    Error Responses

    Status Code Description
    404 Not Found, which may occur if any of the following are true: the MarkupBurner has not completed yet or no such MarkupBurner exists or no such ViewingSession exists
    405 Method Not Allowed, if GET method is not used.

    Examples

    Request

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

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