Introduction

The PrizmDoc OCR REST API allows your application to take a source image as input and produce a JSON output.

Available URLs

POST /prizmdoc/api/v1/ocrReaders

Creates and starts a new OCR process.

The process is started by this request, but a response is sent before the process is complete. Use the GET /prizmdoc/api/v1/ocrReaders/{processId} URL below to get the state and results of an in-progress or completed OCR process.

NOTE: PrizmDoc OCR REST API supports the following input file types:

• TIFF
• JPEG
• PNG

Request

Request Headers

Request Body

JSON object conforming to the following:

• input

  • source (Object) Required. An object that defines the source image.
    • fileId (String) Required. The ID of the work file which represents the source image that will be edited. See the work file API topic to find out how to upload a work file.

  • fields (Array of Objects) Allows users to specify multiple areas to be read in a single call to the Worker.

    • area (Object) The bounding rectangular area of the recognized text. (Default behavior is to read the whole page.)
      • x (Integer) The distance, in pixels, from the left edge of the image to the left edge of the bounding rectangular area of the recognized text.
      • y (Integer) The distance, in pixels, from the top edge of the image to the top edge of the bounding rectangular area of the recognized text.
      • width (Integer) The width, in pixels, of the bounding rectangular area of the recognized text.
      • height (Integer) The height, in pixels, of the bounding rectangular area of the recognized text.
    • page (String) For multi-page images, the page on which the field is expected to be found. This may instead be set to "all" to indicate that the field should be read on every page of the document. The "all" value is only valid when only one field is requested. The default value is 1. Examples:
      • page: 3
      • page: "all"

    • languages (Array of Strings) An array of predefined language sets for valid characters.

      • The "english" characters [A..Z a..z] are available in most languages, including "greek" and "cyrillic".
      • Multiple languages must be in the same language family with following exceptions:
        • "thai" and "english" may be selected together even though they are in different language families.
        • "vietnamese" and "english" may be selected together even though they are in different language families.
      • When "chineseSimplified" and "chineseTraditional" are selected, both languages are read and the character with the highest confidence is used in the result.
      • "chineseSimplified", "chineseTraditional", "chineseTraditionalHK", "japanese", "korean", "thai" or "vietnamese" are only available if the PrizmDoc OCR REST API has been licensed for Asian languages.

      Choose language(s) from this predefined list:

      • "afrikaans"
      • "albanian"
      • "azerbaijaniCyrillic"
      • "azerbaijaniLatin"
      • "baltic"
      • "basque"
      • "belarusian"
      • "bosnianLatin"
      • "bulgarian"
      • "catalan"
      • "centralEuropean"
      • "chineseSimplified"
      • "chineseTraditional"
      • "chineseTraditionalHK"
      • "croatian"
      • "cyrillic"
      • "czech"
      • "danish"
      • "dutch"
      • "english"
      • "estonian"
      • "faroese"
      • "finnish"
      • "french"
      • "frisian"
      • "german"
      • "greek"
      • "guarani"
      • "hani"
      • "hungarian"
      • "icelandic"
      • "indonesian"
      • "irish"
      • "italian"
      • "japanese"
      • "kazakhcyrillic"
      • "kazakhLatin"
      • "kirghizCyrillic"
      • "kirundi"
      • "korean"
      • "latin"
      • "latvian"
      • "lithuanian"
      • "luxembourgish"
      • "macedonian"
      • "malay"
      • "norwegian"
      • "polish"
      • "portuguese"
      • "quechua"
      • "rhaetoRomantic"
      • "romanian"
      • "russian"
      • "serbianCyrillic"
      • "serbianLatin"
      • "shona"
      • "slovak"
      • "slovenian"
      • "somali"
      • "sorbian"
      • "spanish"
      • "tajikCyrillic"
      • "thai"
      • "turkish"
      • "turkmenCyrillic"
      • "turkmenLatin"
      • "ukrainian"
      • "uzbekCyrillic"
      • "uzbekLatin"
      • "vietnamese"
      • "westernEuropean (Default)
      • "wolof"
      • "xhosa"
      • "zulu"
    • characterSet (String) A string used to define the character set to be recognized by the OCR engine. This should accept shortcuts such as [0-9] for all numeric characters. The default value for this is AllCharacters set for the specified language(s).
    • validation (Object) Object which provides properties for validating recognized text. By default, no validation will be performed.
      • fieldType (String) Used to control validation of recognized text. Must be one of the following values:
        • "general" (default) - Recognizes all known characters.
        • "regularExpression" - Attempts to validate recognition results with a provided regular expression. When fieldType is set to this value, the regularExpression property must not be empty.
        • "dataValidationList" - Attempts to match recognition results against a provided list of strings. When fieldType is set to this value, the dataValidationList property must not be empty.
      • regularExpression (String) Regular expression string associated with the field type. Using this property requires setting the fieldType property.
      • regularExpressionCaseInsensitivity (Boolean) Sets case insensitivity of user regular expressions. Default value is "false".
      • dataValidationList (Array of Strings) Array of strings to be used for data validation. Entries must be 80 characters or less for each data validation. By default the list should be empty. Using this property requires setting the fieldType property.
  • defaultHorizontalResolution (Integer) The default horizontal resolution expressed in DPI. The default value is 300 and the field will accept values ranging from 70 to 2400.
  • defaultVerticalResolution (Integer) The default vertical resolution expressed in DPI. The default value is 300 and the field will accept values ranging from 70 to 2400.
  • minimumCharacterConfidence (Integer) The confidence value below which a character is rejected and replaced with the rejection character. The default value is 0 and the values can range from 0 to 100.
  • rejectionCharacter (String) String with a length of 1 used as a replacement for any character with a confidence below the minimum character confidence. The default value is "~" and this accepts every character except the null character.
  • segmentation (Object) Segmentation parameters including detecting spaces, blobs, lines, and merged characters.
    • detectSpaces (Boolean) Determines whether spaces are allowed. By default this is set to "true".
    • multipleTextLines (Boolean) This property is used to allow the recognition of multiple text lines. By default this is set to "true".
  • enableAutoRotation (Boolean) When set to "true", the source image will be analyzed to determine which orientation will provide the most relevant results and automatically use that orientation for scanning. By default this is set to "false". If the source image is rotated to improve recognition, the orientation property in the output will tell how the image was rotated.
  • outputDetailLevel (String) Determines how much detail will be returned.
    • "text" (default) - Produces results for only the recognized text, without details about text lines or individual characters.
    • "textLines" - Produces results for text lines but not for individual characters.
    • "characters" - Produces results for text lines and characters, but not alternatives to the recognized characters.
    • "alternateCharacters" - Produces results for text lines, characters, and alternatives to those characters.

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 OCR process.
• expirationDateTime (String) The date and time (in ISO 8601 Extended Format) when the OCR process will be deleted.
• state (String) The current state of the OCR process running on the server. The response will always be "processing".

Error Responses

Error response will have http status code set to one of following values and the JSON object will contain a property errorCode indicating the type of error:

Example

Request

POST /prizmdoc/api/v1/ocrReaders
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
    },
    "minSecondsAvailable": 60
  }
}

Response

HTTP 200 OK
Content-Type: application/json
{
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "expirationDateTime": "2019-02-07T13:24:35.395Z",
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
    },
  }
  "state": "processing"
}

GET /prizmdoc/api/v1/ocrReaders/{processId}

Gets the state and result of an existing OCR process created by POST /prizmdoc/api/v1/ocrReaders.

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

When state is "complete", the response will include the OCR Result object that was detected by the OCR process.

If the OCR process encountered an error, the state property will be set to "error" and the errorCode property will contain an error code string.

Request

URL Parameters

Successful Response

Response body

JSON object with the following properties:

• input (Object) A copy of the POST /prizmdoc/api/v1/ocrReaders request body input object we accepted to create the OCR process.
• processId (String) The id of the OCR process.
• expirationDateTime (String) The date and time (in ISO 8601 Extended Format) when the OCR process will be deleted.
• state (String) The current state of the OCR process running on the server. It will be one of the following values:
  • "processing" - The OCR process is in progress.
  • "complete" - The OCR process is completed.
  • "error" - The OCR process returns an error.
• errorCode (String) An error code string if a problem occurred during the OCR process. Only present when state is "error".
• output (Object) Describes the output result. Only present when state is "complete".
  • fileId (String) The ID of a work file that contains the results. The content of the work file will be the JSON object described below.

Output Work File Contents

Because the result can, in rare cases, be quite large, it will be stored separately.

The work file specified in a response body for GET /prizmdoc/api/v1/ocrReaders request will contain a single JSON object with the following structure:

• fields (Array of Objects) Contains an object containing the results object returned from the OCR API
  • area (Object)
    • x (Integer) The distance, in pixels, from the left edge of the image to the left edge of the bounding rectangular area of the recognized text.
    • y (Integer) The distance, in pixels, from the top edge of the image to the top edge of the bounding rectangular area of the recognized text.
    • width (Integer) The width, in pixels, of the bounding rectangular area of the recognized text.
    • height (Integer) The height, in pixels, of the bounding rectangular area of the recognized text.
  • confidence (Integer) Confidence value of characters read. Value range is 0-100.
  • text (String) Text block result.
  • orientation (Integer) The orientation of the text located in the field, measured in 90 degree increments of clockwise rotation. For example, when recognizing text rotated so that the top edge of the block is to the right, an orientation of 90 degrees will be reported.
  • page (Integer) In a multi-page image, the page number on which the text was found.
  • fieldTypeMatched (Boolean) When matching recognition results against a regex or validation list, this property will be set to indicate that the results match the specified field type.
• textLines (Array of Objects) An array describing recognized lines of text. This property will be present only if outputDetailLevel was "textLines", "characters" or "alternateCharacters".
  • area (Object)
    • x (Integer) The distance, in pixels, from the left edge of the image to the left edge of the bounding rectangular area of the text line.
    • y (Integer) The distance, in pixels, from the top edge of the image to the top edge of the bounding rectangular area of the text line.
    • width (Integer) The width, in pixels, of the bounding rectangular area of the text line.
    • height (Integer) The height, in pixels, of the bounding rectangular area of the text line.
  • confidence (Integer) Confidence value of characters read. Value range is 0-100.
  • text (String) Characters in the text line.
  • characters (Array of Objects) An array describing recognized characters within the text line. This property will be present only if outputDetailLevel was "characters" or "alternateCharacters".
    • area (Object)
      • x (Integer) The distance, in pixels, from the left edge of the image to the left edge of the bounding rectangular area of the character.
      • y (Integer) The distance, in pixels, from the top edge of the image to the top edge of the bounding rectangular area of the character.
      • width (Integer) The width, in pixels, of the bounding rectangular area of the character.
      • height (Integer) The height, in pixels, of the bounding rectangular area of the character.
    • confidence (Integer) Confidence value of character. Value range is 0-100.
    • text (String) The recognized character.
    • alternateCharacters (Array of Objects) An array describing alternatives to the recognized character. This property will be present only if outputDetailLevel was "alternateCharacters". If there are no alternatives to a character, this property will still be present, but the array will be empty.
      • confidence (Integer) Confidence value of the alternate character. Value range is 0-100.
      • text (String) The alternate character.

Error Responses

Error response will have http status code set to one of following values and the JSON object will contain a property errorCode indicating the type of error:

Examples

Request

GET /prizmdoc/api/v1/ocrReaders/iFhSZRvrz2vtFjcTSi9Qlg

Successful Responses

When outputDetailLevel is "text"

When the OCR process completes without errors:

HTTP 200 OK
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
    }
  },
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "expirationDateTime": "2019-02-07T13:24:35.395Z",
  "state": "complete",
  "output": {
    "fileId": "Pke8nZe25atHKa7qbDdw4g"
   }
}

The results will be stored in the work file indicated by the response above ("Pke8nZe25atHKa7qbDdw4g") and will look like this:

{
  "fields": [{
    "area": {
      "x": 496,
      "y": 81,
      "width": 646,
      "height": 99
    },
    "confidence": 100,
    "text": "This text has been read by OCR"
  }]
}

When outputDetailLevel is "characters"

When the OCR process completes without errors:

HTTP 200 OK
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
    },
    "outputDetailLevel": "characters"
  },
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "expirationDateTime": "2019-02-07T13:24:35.395Z",
  "state": "complete",
  "output": {
    "fileId": "Pke8nZe25atHKa7qbDdw4g"
   }
}

The results will be stored in the work file indicated by the response above ("Pke8nZe25atHKa7qbDdw4g") and will look like this:

{
  "fields": [{
    "area": {
      "x": 496,
      "y": 81,
      "width": 646,
      "height": 99
    },
    "confidence": 100,
    "text": "This text has been read by OCR",
    "textLines": [{
      "area": {
        "x": 496,
        "y": 81,
        "width": 646,
        "height": 43
      },
      "confidence": 100,
      "text": "This text has been read",
      "characters": [{
        "area": {
          "x": 496,
          "y": 81,
          "width": 22,
          "height": 40
        },
        "confidence": 100,
        "text": "T",
      },
      ...
      ]
    },
    ...
    ]
  }]
}

Error Responses

Process ID

Response when an OCR process does not exist for the given processId:

HTTP 404
Content-Type: application/json
{
  "errorCode": "ResourceNotFound",
  "errorDetails": {
    "in": "url",
    "at": "processId",
  },
}

Response when an OCR process does exist for the given processId, but has passed its expiration time:

HTTP 410
Content-Type: application/json
{
  "errorCode": "ResourceExpired",
  "errorDetails": {
    "in": "url",
    "at": "processId",
  },
}

Input Source

Response when source document is a file format that is not supported by the OCR API:

HTTP 200 OK
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
    }
  },
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "state": "error",
  "errorCode": "UnsupportedFileFormat",
  "errorDetails": {
    "in": "process",
    "at": "input.source.fileId"
  },
  "expirationDateTime": "2019-02-07T13:24:35.395Z"
}

Page Number

Response when an invalid page number or out of range page number was specified for a page parameter:

HTTP 200 OK
Content-Type: application/json
{
  "processId": "dy3fkHUPJIp2bNGt6oja4g",
  "state": "error",
  "input": {
    "source": {
      "fileId": "BOhWDnPNhDrJDRFjtY0Zlw"
    },
    "fields": [
      {
        "area": {
          "x": 0,
          "y": 0,
          "width": 0,
          "height": 0
        },
        "page": "forty"
      }
    ],
    "minimumCharacterConfidence": 0,
    "defaultHorizontalResolution": 300
  },
  "errorCode": "InvalidInput",
  "errorDetails": {
    "in": "process",
    "at": "input.fields[0].page"
  }
}

Response when "all" is provided for a page parameter on a request that includes multiple fields:

HTTP 200 OK
Content-Type: application/json
{
  "processId": "dy3fkHUPJIp2bNGt6oja4g",
  "state": "error",
  "input": {
    "source": {
      "fileId": "BOhWDnPNhDrJDRFjtY0Zlw"
    },
    "fields": [
      {
        "area": {
          "x": 0,
          "y": 0,
          "width": 0,
          "height": 0
        },
        "page": "1"
      },
      {
        "area": {
          "x": 0,
          "y": 0,
          "width": 0,
          "height": 0
        },
        "page": "all"
      }
    ],
    "minimumCharacterConfidence": 0,
    "defaultHorizontalResolution": 300
  },
  "errorCode": "InvalidInput",
  "errorDetails": {
    "in": "process",
    "at": "input.fields[1].page",
    "when": [
      "otherInput": {
        "in": "process",
        "at": "input.fields.length",
        "greaterThan": 1
      }
    ]
  }
}

Auto Rotation

Response when a non-boolean value is provided for the enableAutoRotation input parameter:

HTTP 200 OK
Content-Type: application/json
{
  "processId": "dy3fkHUPJIp2bNGt6oja4g",
  "state": "error",
  "input": {
    "source": {
      "fileId": "BOhWDnPNhDrJDRFjtY0Zlw"
    },
    "fields": [
      {
        "area": {
          "x": 0,
          "y": 0,
          "width": 0,
          "height": 0
        }
      }
    ],
    "minimumCharacterConfidence": 0,
    "defaultHorizontalResolution": 300,
    "enableAutoRotation": "yes"
  },
  "errorCode": "InvalidInput",
  "errorDetails": {
    "in": "process",
    "at": "input.enableAutoRotation",
    "expected": {
      "type": "boolean"
    }
  }
}

Languages

Response when multiple languages are provided, but they are from conflicting language families:

HTTP 200 OK
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ",
      "fields": [{
        "languages": [
          "ukrainian",
          "chineseTraditional"
        ]
      }]
    }
  },
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "state": "error",
  "errorCode": "MismatchedLanguageFamilies",
  "errorDetails": {
    "in": "process",
    "at": "input.fields[0].languages"
  },
  "expirationDateTime": "2019-02-07T13:24:35.395Z"
}

Field Type

Response when regularExpression or dataValidationList is provided without specifying the fieldType:

HTTP 200 OK
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ",
      "fields": [{
        "validation": {
          "regularExpression": "[ab]+"
        }
      }]
    }
  },
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "state": "error",
  "errorCode": "UnrecognizedInput",
  "errorDetails": {
    "in": "process",
    "at": "input.source.fields[0].validation.fieldType",
    "expected": {
      "value": "regularExpression"
    },
    "when": [{
      "otherInput": {
        "in": "process",
        "at": "input.field[0].validation.regularExpression"
      }
    }]
  },
  "expirationDateTime": "2019-02-07T13:24:35.395Z"
}

Response when fieldType is set but the regularExpression or dataValidationList is not provided:

HTTP 200 OK
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ",
      "fields": [{
        "validation": {
          "fieldType": "regularExpression"
        }
      }]
    }
  },
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "state": "error",
  "errorCode": "MissingInput",
  "errorDetails": {
    "in": "process",
    "at": "input.field[0].validation.regularExpression",
    "expected": {
      "type": "string"
    },
    "when": [{
      "otherInput": {
        "in": "process",
        "at": "input.field[0].validation.fieldType",
        "equals": "regularExpression"
      }
    }]
  },
  "expirationDateTime": "2019-02-07T13:24:35.395Z"
}

Response when regularExpression or dataValidationList is set with a non-matching fieldType:

HTTP 200 OK
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ",
      "fields": [{
        "validation": {
          "fieldType": "dataValidationList",
          "regularExpression": "[ab]+"
        }
      }]
    }
  },
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "state": "error",
  "errorCode": "UnrecognizedInput",
  "errorDetails": {
    "in": "process",
    "at": "input.field[0].validation.regularExpression",
    "expected": {
      "type": "string"
    },
    "when": [{
      "otherInput": {
        "in": "process",
        "at": "input.field[0].validation.fieldType",
        "is": {
          "value": "dataValidationList"
        }
      }
    }]
  },
  "expirationDateTime": "2019-02-07T13:24:35.395Z"
}