PrizmDoc® v14.2 Release - Updated
PrizmDoc / API Reference / PrizmDoc Server REST API / Viewer Support / Document Classifiers
In This Topic
    Document Classifiers
    In This Topic

    Introduction

    The search context and Document Classifiers REST APIs (which is part of the "Auto Tagging and Classification" feature) allow your application to determine a classification for a document.

    A document classifier resource represents an asynchronous document classification process and yields a classification when available.

    IMPORTANT: This API will continue to evolve as we refine these features and extend our cloud service offerings.

    Available URLs

    URL Description
    POST /v2/documentClassifiers Creates a new document classifier for a search context, starting the process of classification.
    GET /v2/documentClassifiers/{processId} Gets information about a document classifier.

    POST /v2/documentClassifiers

    Creates a new document classifier for a search context, starting the process of classification.

    After a successful POST to create the document classifier, we immediately begin a background process to start a document classification for you to GET. Once the full text of the document has been searched and classified, the document classifier state will change from "processing" to "complete".

    Request

    Request Headers

    Name Description
    Content-Type Must be application/json
    Accusoft-Affinity-Token The affinityToken of the search context specified by input.contextId. Required when server clustering is enabled.

    Request Body

    • input
      • contextId (String) Required. Identifies the search context which holds the full-text data to classify.
      • classifications (Array of strings) Required. A list of classifications from which to select a classification for the document.
    • minSecondsAvailable (Integer) The minimum number of seconds this document classifier 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 document classifier.

    • input (Object) Input we accepted to create the document classifier.
    • processId (String) Unique id for this document classifier.
    • affinityToken (String) Affinity token for this document classifier. Present when clustering is enabled.
    • state (String) State of document classification.
      • "processing" - The classification is still being executed.
      • "complete" - The classification is complete.
      • "error" - There was a problem performing the classification.
    • percentComplete (Integer) Percentage of document classification which has completed (from 0 to 100).
    • expirationDateTime (String) Currently planned date and time when the document classifier resource will expire and no longer be available for use. Format is RFC 3339 Internet Date/Time profile of ISO 8601, e.g. "2024-11-05T08:15:30.494Z".

    Error Responses

    Status Code JSON errorCode Description
    400 "MissingInput" Can occur when clustering is enabled and an Accusoft-Affinity-Token request header was not provided.
    480 "MissingInput" A required input value was not provided. See errorDetails in the response body.
    480 "InvalidInput" An invalid input value was used. See errorDetails in the response body.
    480 "ResourceNotFound" Can occur when the search context specified by contextId could not be found. See errorDetails in the response body.
    480 "ResourceNotUsable" Can occur when the search context specified by contextId is not usable. See errorDetails in the response body.
    480 "FeatureNotLicensed" You are not licensed to use the document classification feature.
    580 "InternalError" The server encountered an internal error when handling the request.

    Example

    Request

    POST prizmdoc_server_base_url/v2/documentClassifiers
    Content-Type: application/json
    Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=
    
    {
      "input": {
        "contextId": "ElkNzWtrUJp4rXI5YnLUgw",
        "classifications": ["geography", "health", "history", "mathematics", "nature", "philosophy", "technology"]
      },
      "minSecondsAvailable": 600
    }
    
    

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

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "input": {
        "contextId": "ElkNzWtrUJp4rXI5YnLUgw",
        "classifications": ["geography", "health", "history", "mathematics", "nature", "philosophy", "technology"]
      },
      "processId": "pR5X6nPDgMwat6cxlmn0Q3",
      "state": "processing",
      "percentComplete": 0,
      "expirationDateTime": "2024-12-17T20:38:39.796Z"
    }
    
    

    GET /v2/documentClassifiers/{processId}

    Gets a classification of the document.

    This URL is designed to give you the document classification when it becomes available.

    Request

    URL Parameters

    Parameter Description
    {processId} The processId which identifies the document classifier.

    Successful Response

    Response Body

    JSON with the available document classification.

    • classification (String) Always present. String containing the document classification. If no classification is available, this string will be empty.

    Error Responses

    Status Code JSON errorCode Description
    404 - No document classifier with the provided {processId} could be found.
    400 "MissingInput" Can occur when clustering is enabled and an Accusoft-Affinity-Token request header was not provided.
    480 "InvalidInput" An invalid input value was used. See errorDetails in the response body.
    480 "ResourceNotUsable" Can occur when the document classifier is in a state of "error". You may be able to get more information from a GET /v2/documentClassifiers/{processId}.
    580 "InternalError" The server encountered an internal error when handling the request.

    Example

    Here is an example request and response illustrating how you would acquire the classification from the document classifier.

    You would GET like so:

    GET prizmdoc_server_base_url/v2/documentClassifiers/pR5X6nPDgMwat6cxlmn0Q3
    
    

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

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "classification": "technology"
    }