Introduction

The redaction creators REST API allows your application to automatically create redaction definitions for a document based on a given set of text-matching rules.

For application development in.NET, we recommend using the PrizmDoc Server.NET SDK instead of using the PrizmDoc Server REST API directly. See the How to Create a Redacted PDF topic in the.NET SDK documentation for an example of how to easily create redactions from a set of Regular Expression rules.

A redaction creator takes as input a source document and a set of text-matching regular expressions and produces as output a markup JSON file (or, if using the deprecated endpoints, a markup XML file). The output markup can then be used with the markup burners REST API to “burn” the redactions into a document.

Available URLs

Deprecated URLs

POST /v2/redactionCreators

Creates and starts a new redaction creator process.

A redaction creator represents a process that runs on the server which searches a document for text fragments matching specified rules and then, based on any matches, creates a new JSON Markup document containing redaction markup. The redaction markup that is created by this process can be used with the markup burner API to "burn" the redactions into a document.

The server process to create the redaction markup is started by this request, but a response is sent before the process is complete. Use the GET /v2/redactionCreators/{processId} URL below to get the state and results of an in-progress or completed redaction creator process.

There are two required inputs to create a RedactionCreator:

• One is a WorkFile object that represents the source document whose text will be searched, and
• One or more rules to match and redact the document text.

See the work file API topic for more information about a WorkFile.

A new markup document will be created that will contain the redaction markup. The new document will be made available by a new WorkFile ID.

Request

Request Headers

Request Body

JSON object conforming to the following:

• input
  • source (Object) Required. Describes the document for which the markup will be created. This document will not be modified.
    • fileId (String) Required. The ID of the WorkFile that represents the source document whose text will be searched.
  • rules (Array) Required. The list of rules, each containing a Regular Expression to match the text and markup properties for any matches.
    • find (Object) Required. Describes the way to find matching text in the document.
      • type (String) Required. Must be "regex". The type of the text match algorithm.
      • pattern (String) Required, when type is "regex". The Regular Expression to match within the source document text using a POSIX extended RE (ERE) or basic RE (BRE) syntax.
      • newLineHandling (String) Describes how to treat the new line characters \n in the source document:
        • "spaces" - (Default) Replaces new line characters with spaces upon text search. This allows you to use a pattern of "one two" instead of "one\ntwo" to find a match on the previous and the next text line (the case when the matched words are split between two lines).
        • "newLines" - Leaves new line characters as is. The regex pattern should include new line character(s) to be able to search for the text that may be split between lines.
    • redactWith (Object) Required. Describes how to redact matching text.
      • type (String) Required. Must be "RectangleRedaction". Type of redaction to be created for the matching text.
      • reason (String) Reason the content was redacted, displayed in the center of the redaction annotation.

        NOTE: Only one of "reason" or "reasons" properties can be specified for a specific rule.

      • reasons (Array of strings) Reasons the content was redacted, displayed semicolon space separated in the center of the redaction annotation.

        NOTE: Only one of the "reason" or "reasons" properties can be specified for a specific rule.

      • fontColor (String) Color of the text specified as a 6-character hexadecimal color string with a leading # sign. For example, a value of "#FF0000" will create red text. Default is "#FFFFFF".
      • fillColor (String) Color of the redaction background specified as a 6-character hexadecimal color string with a leading # sign. For example, a value of "#FF0000" will create a red background. Default is "#000000".
      • borderColor (String) Color of the border specified as a 6-character hexadecimal color string with a leading # sign. For example, a value of "#FF0000" will create a red border. Default is "#000000".
      • borderThickness (Integer) Thickness of the border in pixels. Should be greater than 0. Default is 1.

        NOTE: Large borderThickness values may create borders which visually hide content from neighboring redacted text, however, this content will not be removed from the document during burning.

      • data (Object) A property bag of user-defined values. Property values are only allowed to be strings.
• minSecondsAvailable (Integer) The minimum number of seconds this markup creator will remain available so you can GET its status. The actual lifetime may be longer. The default lifetime is defined by the processIds.lifetime central configuration parameter.

Successful Response

Response body

JSON object with the following properties:

• input (Object) A copy of the request body input object.
• processId (String) The id of the new redaction creator process.
• expirationDateTime (String) The date and time (in ISO 8601 Extended Format) when the RedactionCreator will be deleted.
• state (String) The current state of the redaction creation process running on the server. This will always be "processing" in this response.
• percentComplete (Integer) The percentage (0 – 100) complete of the redaction creation process. This will always be 0 in this response.
• affinityToken (String) Affinity token for this search context. Present when clustering is enabled.

Error Responses

Example

Request

POST /v2/redactionCreators
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "NmFzioyWzFM5ADpthsuitw"
    },
    "rules": [{
        "find": {
          "type": "regex",
          "pattern": "wat"
        },
        "redactWith": {
          "type": "RectangleRedaction"
        }
      },
      {
        "find": {
          "type": "regex",
          "pattern": "[0-9]{3}[-]?[0-9]{2}[-]?[0-9]{4}"
        },
        "redactWith": {
          "type": "RectangleRedaction",
          "borderColor": "#FF0000",
          "fillColor": "#FF0000",
          "fontColor": "#000000",
          "reason": "Redacted",
          "data": {
            "author": "John Smith",
            "phone": "+1 123 456 789"
          }
        }
      }
    ]
  }
}

Response

HTTP 200 OK
Content-Type: application/json
{
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "expirationDateTime": "2019-02-07T13:24:35.395Z",
  "input": {
    "source": {
      "fileId": "NmFzioyWzFM5ADpthsuitw"
    },
    "rules": [
    {
        "find": {
          "regex": "wat"
        },
        "redactWith": {
          "type": "RectangleRedaction"
        }
      },
      {
        "find": {
          "regex": "[0-9]{3}[-]?[0-9]{2}[-]?[0-9]{4}"
        },
        "redactWith": {
          "type": "RectangleRedaction",
          "borderColor": "#FF0000",
          "fillColor": "#FF0000",
          "fontColor": "#000000",
          "reason": "Redacted",
          "data": {
            "author": "John Smith",
            "phone": "+1 123 456 789"
          }
        }
      }
    ]
  },
  "state": "processing",
  "percentComplete": 0
}

GET /v2/redactionCreators/{processId}

Gets the state and result of an existing redaction creator process created by POST /v2/redactionCreators.

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

When state is "complete", the new markup document containing redactions will be made available by a new WorkFile ID in the output.markupFileId. See 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" and the errorCode property will contain an error code string.

Request

Request Headers

URL Parameters

Response body

JSON object with the following properties:

• input (Object) A copy of the POST /v2/redactionCreators request body input object we accepted to create the redaction creator process.
• processId (String) The id of the redaction creator process.
• expirationDateTime (String) The date and time (in ISO 8601 Extended Format) when the RedactionCreator will be deleted.
• state (String) The current state of the redaction creation process running on the server. The following values are allowed:
  • "processing" - The redaction creation is in progress.
  • "complete" - The redaction creation is completed.
  • "error" - The redaction creation returns an error.
• percentComplete (Integer) The percentage (0 – 100) complete of the redaction creation process. Will be 100 when state is "complete".
• errorCode (String) An error code string if a problem occurred during the redaction creation process. Only present when state is "error".
• output (Object) The object describes the created markup document. Only present when state is "complete".
  • markupFileId (String) The ID of the new WorkFile that represents a new Markup document specifying the redactions.
• affinityToken (String) Affinity token for this search context. Present when clustering is enabled.

Error Responses and JSON Error Codes

Example

Request

GET /v2/redactionCreators/iFhSZRvrz2vtFjcTSi9Qlg

Successful Response

When the redaction creator process completes with no errors:

HTTP 200 OK
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "NmFzioyWzFM5ADpthsuitw"
    },
    "rules": [
    {
        "find": {
          "regex": "wat"
        },
        "redactWith": {
          "type": "RectangleRedaction"
        }
      },
      {
        "find": {
          "regex": "[0-9]{3}[-]?[0-9]{2}[-]?[0-9]{4}"
        },
        "redactWith": {
          "type": "RectangleRedaction",
          "borderColor": "#FF0000",
          "fillColor": "#FF0000",
          "fontColor": "#000000",
          "reason": "Redacted",
          "data": {
            "author": "John Smith",
            "phone": "+1 123 456 789"
          }
        }
      }
    ]
  },
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "expirationDateTime": "2019-02-07T13:24:35.395Z",
  "state": "complete",
  "percentComplete": 100,
  "output": {
    "markupFileId": "eOsJIqI8aHkxVV0yJug"
  }
}

Error responses

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

HTTP 404
Content-Type: application/json
{
  errorCode: 'ResourceNotFound'
}

When source document is corrupted and Markup can not be created:

HTTP 200 OK
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "NmFzioyWzFM5ADpthsuitw"
    },
    "rules": [
    {
        "find": {
          "regex": "wat"
        },
        "redactWith": {
          "type": "RectangleRedaction"
        }
      },
      {
        "find": {
          "regex": "[0-9]{3}[-]?[0-9]{2}[-]?[0-9]{4}"
        },
        "redactWith": {
          "type": "RectangleRedaction",
          "borderColor": "#FF0000",
          "fillColor": "#FF0000",
          "fontColor": "#000000",
          "reason": "Redacted",
          "data": {
            "author": "John Smith",
            "phone": "+1 123 456 789"
          }
        }
      }
    ]
  },
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "state": "error",
  "errorCode": "MarkupCreationError",
  "percentComplete": 0,
  "expirationDateTime": "2019-02-07T13:24:35.395Z"
}

POST /PCCIS/V1/RedactionCreator

NOTE: This URL has been deprecated and will be removed from the public API in a future release. Please use the newer POST /v2/redactionCreators instead.

Creates and starts a new RedactionCreator.

A RedactionCreator represents a process that runs on the server which searches a document for text matching a Regular Expression and then, based on any matches, creates a new Markup XML document containing redaction markup. The redaction Markup XML that is created by this process can be used with the markup burner API to "burn" the redactions into a document.

The server process to create the redaction markup is started by this request, but a response is sent before the process is complete. Use the GET /PCCIS/V1/RedactionCreator/{processId} URL below to get the state and results of an in-progress or completed RedactionCreator process.

There are two required inputs to create a RedactionCreator:

• One is a WorkFile object that represents the source document whose text will be searched, and
• One or more Regular Expressions to match the document text.

See the work file API topic for more information about a WorkFile.

A new Markup XML document will be created that will contain the redaction markup. The new document will be made available by a new WorkFile ID.

By default, RedactionCreator 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 RedactionCreator.
  • documentFileId (String) Required. The ID of the WorkFile that represents the source document whose text will be searched. This document will not be modified.
  • autoRedactionRegularExpressions (Array of strings) Required. The Regular Expressions to match within the source document text. Multiple Regular Expressions provided in the array will be concatenated into a single Regular Expression using the format: "(regex1)|(regex2)…|(regexN)".
• minSecondsAvailable (Integer) The minimum number of seconds which this RedactionCreator must remain available. If not provided, a configurable default value is used. This value is ignored if it is shorter than the configurable value.

Response Body

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

• input (Object) Input we accepted to create the RedactionCreator.
  • documentFileId (String) The ID of the WorkFile that represents the source document whose text will be searched. This document will not be modified. This is an echo of what was passed in by the request.
  • autoRedactionRegularExpressions (Array of Strings) The Regular Expressions to match within the source document text. 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 RedactionCreator will be deleted.
• processId (String) The ID of the RedactionCreator.
• 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 redaction creation 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)
  • markupFileId (String) The ID of the new WorkFile that represents the new redaction XML markup. This will always be null in this response.
• affinityToken (String) Affinity token for this search context. Present when clustering is enabled.

Error Responses

Examples

Request

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

{
    "input": {
        "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ",
        "autoRedactionRegularExpressions": [
            "[0-9]{3}[-]?[0-9]{2}[-]?[0-9]{4}"
        ]
    },
    "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",
        "autoRedactionRegularExpressions": [
            "[0-9]{3}[-]?[0-9]{2}[-]?[0-9]{4}"
        ]
    },
    "expirationDateTime": "2014-12-17T20:38:39.796Z",
    "processId": "ElkNzWtrUJp4rXI5YnLUgw",
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
    "state": "processing",
    "percentComplete": 0,
    "errorCode": null,
    "output": null
}

GET /PCCIS/V1/RedactionCreator/{processId}

NOTE: This URL has been deprecated and will be removed from the public API in a future release. Please use the newer POST /v2/redactionCreators and GET /v2/redactionCreators/{processId} instead.

Gets the state and result of an existing RedactionCreator.

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

When state is "complete", the new markup XML document containing redactions will be made available by a new WorkFile ID in the output.markupFileId. See 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 source document whose text will be searched. This document will not be modified.
  • autoRedactionRegularExpressions (Array of Strings) The Regular Expressions to match within the source document text.
• expirationDateTime (String) The date and time (in ISO 8601 Extended Format) when the RedactionCreator will be deleted.
• processId (String) The ID of the RedactionCreator.
• state (String) The current state of the redaction creation process running on the server. The following values are allowed:
  • "processing" - The redaction creation is in progress.
  • "complete" - The redaction creation is completed.
  • "error" - The redaction creation returns an error.
• percentComplete (Integer) The percentage (0 – 100) complete of the redaction creation process.
• errorCode (String) An error code string if a problem occurred during the redaction creation process.
• output (Object)
  • markupFileId (String) The ID of the new WorkFile that represents a new XML Markup document specifying the redactions.
• affinityToken (String) Affinity token for this search context. Present when clustering is enabled.

Error Responses

Examples

Request

GET prizmdoc_server_base_url/PCCIS/V1/RedactionCreator/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",
        "autoRedactionRegularExpressions": [
            "[0-9]{3}[-]?[0-9]{2}[-]?[0-9]{4}"
        ]
    },
    "expirationDateTime": "2014-12-17T20:38:39.796Z",
    "processId": "ElkNzWtrUJp4rXI5YnLUgw",
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
    "state": "processing",
    "percentComplete": 0,
    "errorCode": null,
    "output": null
}

Response when the state is "complete"

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

{
    "input": {
        "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ",
        "autoRedactionRegularExpressions": [
            "[0-9]{3}[-]?[0-9]{2}[-]?[0-9]{4}"
        ]
    },
    "expirationDateTime": "2014-12-17T20:38:39.796Z",
    "processId": "ElkNzWtrUJp4rXI5YnLUgw",
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
    "state": "complete",
    "percentComplete": 100,
    "errorCode": null,
    "output": {
        "markupFileId": "vry3FPE0zQqYwhzndRccOQ"
    }
}

Response when the state is "error" because the work file that represents the source document whose text will be searched 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"
}