Introduction

The search context and Personally Identifiable Information (PII) Detectors REST API is used by our Viewer to detect PII in a document which is currently being viewed.

NOTE: This REST API is designed primarily for our Viewer. If your application needs to perform PII detection without a viewer involved, we recommend you use PrizmDoc Server’s search context and PII detectors REST APIs directly.

Available URLs

POST /v2/viewingSessions/{viewingSessionId}/piiDetectors

Creates a new PII detector for a viewing session’s source document, starting the process of detecting PII.

After a successful POST to create the PII detector, we immediately begin a background process to start populating PII entities for you to GET. You do not need to wait for the full set of PII entities to be available; you can start retrieving partial PII entities as soon as they are available. Once the full text of the document has been searched and no more PII entities will be added, the PII detector state will change from "processing" to "complete".

Request

Request Headers

Request Body

• minSecondsAvailable (Integer) The minimum number of seconds this PII detector will remain available. The actual lifetime may be longer. The default lifetime is defined by the processIds.lifetime central configuration parameter.

Successful Response

Response Body

JSON with metadata about the created PII detector.

• processId (String) Unique id for this PII detector.
• affinityToken (String) Affinity token for this PII detector. Present when clustering is enabled.
• state (String) State of detecting PII.
  • "processing" - The detection is still being executed. Additional PII entities may become available.
  • "complete" - The detection is complete. No additional PII entities will become available.
  • "error" - There was a problem performing the detection. No additional PII entities will become available.
• percentComplete (Integer) Percentage of PII detection which has completed (from 0 to 100).
• expirationDateTime (String) Currently planned date and time when the PII detector resource will expire and no longer be available for use. Format is RFC 3339 Internet Date/Time profile of ISO 8601, e.g. "2023-11-05T08:15:30.494Z".

Error Responses

Example

Request

This POST begins PII detection:

POST pas_base_url/v2/viewingSessions/XYZ.../piiDetectors
Content-Type: application/json

{
  "minSecondsAvailable": 600
}

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

Response

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

{
  "processId": "pR5X6nPDgMwat6cxlmn0Q3",
  "state": "processing",
  "percentComplete": 0,
  "expirationDateTime": "2023-12-17T20:38:39.796Z"
}

GET /v2/piiDetectors/{processId}/entities?limit={limit}&continueToken={continueToken}

Gets a block of newly-available PII entities up to a limit.

This URL is designed to give you the PII entities in chunks as they become available. Each GET request will return the currently-known PII entities up to a limit (default is 100). If a response contains a continueToken, it indicates that additional PII entities may be available and that you should issue another GET request using that continueToken as a query string parameter to skip the PII entities you have already received. As long as a response contains a continueToken, use it to issue a subsequent GET for more PII entities. When you encounter a response which does not have a continueToken, you have received all of the PII entities and no more GET requests are necessary.

In order to optimize the number of network requests you make, any response which contains a continueToken will also contain a continueAfter value with a recommended number of milliseconds you should wait before sending the next GET request.

Request

URL Parameters

Request Headers

Successful Response

Response Body

JSON with any available PII entities.

• entities (Array of Objects) Always present. Array of newly-available PII entities. If no new PII entities are available, this array will be empty.
  • id (Integer) Unique number assigned to this PII entity.
  • pageIndex (Integer) Zero-indexed page number where this PII entity occurs in the document.
  • text (String) The text of PII entity.
  • lineGroups (Array of Objects) An array of text line groups that indicate where the PII entity is located.
    • pageIndex (Integer) Zero-indexed page number where this PII entity occurs in the document.
    • pageData (Object) Information about the dimensions of the page where this PII entity occurs.
      • width (Number) Width of the page.
      • height (Number) Height of the page.
    • boundingRectangle (Object) Bounding rectangle dimensions of the PII entity on the first page where it occurs.
      • x (Number) Distance from the left edge of the page to the left edge of the PII entity bounding box.
      • y (Number) Distance from the top edge of the page to the top edge of the PII entity bounding box.
      • width (Number) Width of the PII entity bounding box.
      • height (Number) Height of the PII entity bounding box.
    • lines (Array of Objects) Array of rectangles for each line of the PII entity on the page where it occurs. If the PII entity is on one line, the result is a single array item with a rectangle equal to boundingRectangle. If the PII entity is on multiple lines, all rectangles in the array will be within the bounds of the boundingRectangle.
      • x (Number) Distance from the left edge of the page to the left edge of the PII entity line rectangle.
      • y (Number) Distance from the top edge of the page to the top edge of the PII entity line rectangle.
      • width (Number) Width of the PII entity line rectangle.
      • height (Number) Height of the PII entity line rectangle.
  • startIndex (Integer) The index of the full-page text where the PII entity begins.
  • type (string) The entity’s type.
  • score (Number) A number ranging from 0 to 1 that represents the level of confidence in the accuracy of the detection.
• pagesWithoutText (Array of Integers) Always present. Currently known pages in the document which do not contain any text content at all. Values are zero-indexed page numbers. If the PII detector is still processing (a continueToken is present in the response), the data should be considered partial. Note that, unlike PII entities, this value is cumulative (we always deliver the entire set of pages we know to not contain text data).
• continueToken (String) When present, indicates that more PII entities may be available. An additional GET request should be made for more PII entities using this value as the continueToken query string parameter. When not present, indicates that the detection is complete and no further PII entities will be available.
• continueAfter (Number) Recommended milliseconds to delay before issuing the next GET request for more PII entities.

Error Responses

Example

Here is an example sequence of requests and responses illustrating how you would acquire the full set of PII entities for the PII detector (for brevity, the total number of PII entities in this example is small).

You would start with an initial GET:

GET pas_base_url/v2/piiDetectors/pR5X6nPDgMwat6cxlmn0Q3/entities
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

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

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

{
  "entities": [
    {
      "id": 0,
      "pageIndex": 0,
      "text": "John Doe",
      "lineGroups": [
        "pageIndex": 0,
        "boundingRectangle": { "x": 24.20, "y": 13.74, "width": 234.20, "height": 26.10 },
        "lines": [{ "x": 24.20, "y": 13.74, "width": 234.20, "height": 26.10 }],
        "pageData": { "width": 612, "height": 792 }
      ],
      "startIndex": 19,
      "type": "person",
      "score": 1.0
    },
    {
      "id": 1,
      "pageIndex": 0,
      "text": "(555) 555-5555",
      "lineGroups": [
        "pageIndex": 0,
        "boundingRectangle": { "x": 156.07, "y": 352.19, "width": 105.00, "height": 13.41 },
        "lines": [{ "x": 156.07, "y": 352.19, "width": 105.00, "height": 13.41 }],
        "pageData": { "width": 612, "height": 792 }
      ],
      "startIndex": 527,
      "type": "phoneNumber",
      "score": 1.0
    }
  ],
  "pagesWithoutText": [],
  "continueToken": "Cx07GHlkmi32gxAQhv49WZ",
  "continueAfter": 500
}

The initial response has given us two PII entities for the first page of the document (page index 0) and a continueToken which we should use to get more PII entities after waiting 500 milliseconds.

So, half a second later, we issue a follow-up request with the continueToken passed in as a query string parameter (so we skip over the results we already have):

GET pas_base_url/v2/piiDetectors/pR5X6nPDgMwat6cxlmn0Q3/entities?continueToken=Cx07GHlkmi32gxAQhv49WZ
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

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

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

{
  "entities": [
    {
      "id": 2,
      "pageIndex": 1,
      "text": "Jane Doe",
      "lineGroups": [
        "pageIndex": 0,
        "boundingRectangle": { "x": 310.21, "y": 562.14, "width": 254.03, "height": 26.10 },
        "lines": [{ "x": 310.21, "y": 562.14, "width": 254.03, "height": 26.10 }],
        "pageData": { "width": 612, "height": 792 }
      ],
      "startIndex": 652,
      "type": "person",
      "score": 1.0
    }
  ],
  "pagesWithoutText": [2,3],
  "continueToken": "B4uGe7m0ZtxR3lkqA07Nmj",
  "continueAfter": 500
}

This time we get back a new PII entity as well as some new information about pagesWithoutText: we now know that at least page indices 2 and 3 (zero-indexed page numbers) have no text at all.

The presence of a new continueToken tells us there may be more PII entities, so we submit another request with the new continueToken:

GET pas_base_url/v2/piiDetectors/pR5X6nPDgMwat6cxlmn0Q3/entities?continueToken=B4uGe7m0ZtxR3lkqA07Nmj
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

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

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

{
  "entities": [
    {
      "id": 3,
      "pageIndex": 5,
      "text": "(555) 555-1234",
      "lineGroups": [
        "pageIndex": 0,
        "boundingRectangle": { "x": 67.00, "y": 142.53, "width": 254.03, "height": 26.10 },
        "lines": [{ "x": 67.00, "y": 142.53, "width": 254.03, "height": 26.10 }],
        "pageData": { "width": 612, "height": 792 }
      ],
      "startIndex": 113,
      "type": "phoneNumber",
      "score": 1.0
    }
  ],
  "pagesWithoutText": [2,3,4]
}

This time we get a new PII entity for page index 5, and we now know that page indices 2, 3, and 4 all contain no text at all (apparently this was not much of a whitepaper!). The lack of a continueToken tells us we have received all of the PII entities, so there are no more GET requests to make.

DELETE /v2/piiDetectors/processId

Cancels the PII detection process. Further requests using this processId will return errors.

Request

URL Parameters

Request Headers

Successful Response

HTTP/1.1 204 No Content

Error Responses