Regula Document Reader Web API (7.1.0)

Documents recognition as easy as reading two bytes.

Clients:

  • JavaScript client for the browser and node.js based on axios
  • Java client compatible with jvm and android
  • Python 3.5+ client
  • C# client for .NET & .NET Core

process

Everything about perfoming request and parsing response

Process list of documents images and return extracted data

header Parameters
X-RequestID
string
Request Body schema: application/json
tag
string

session id

required
object (ProcessParams)
Array of objects (ProcessRequestImage)
livePortrait
string <base64>

Live portrait photo

extPortrait
string <base64>

Portrait photo from an external source

object (ContainerList)

List with various objects, containing processing results

object (ProcessSystemInfo)
object

Free-form object to be included in response. Must be object, not list or simple value. Do not affect document processing. Use it freely to pass your app params. Stored in process logs.

Responses

Response Schema: application/json
ChipPage
integer (RfidLocation)
Enum: 0 1 2

Determines the presence and location of an RFID chip in a document. 0 - no rfid chip; 1 - chip is located in the document data page; 2 - chip is located in the back page or inlay of the document

ProcessingFinished
required
integer (ProcessingStatus)
Enum: 0 1 2
required
object (ContainerList)

List with various objects, containing processing results

required
object (TransactionInfo)
log
string

Base64 encoded transaction processing log

object

Free-form object provided in request. See passBackObject property of ProcessRequest.

morePagesAvailable
integer
elapsedTime
integer

Time the document processing has taken, ms.

Request samples

Content type
application/json
{
  • "tag": "string",
  • "processParam": {
    • "lcidFilter": [ ],
    • "lcidIgnoreFilter": [ ],
    • "oneShotIdentification": true,
    • "useFaceApi": true,
    • "faceApi": {},
    • "doDetectCan": true,
    • "imageOutputMaxHeight": 0,
    • "imageOutputMaxWidth": 0,
    • "scenario": "Mrz",
    • "resultTypeOutput": [
      • 1
      ],
    • "doublePageSpread": true,
    • "generateDoublePageSpreadImage": true,
    • "fieldTypesFilter": [
      • 0
      ],
    • "dateFormat": "MM/dd/yyyy",
    • "measureSystem": 0,
    • "imageDpiOutMax": 0,
    • "alreadyCropped": true,
    • "customParams": { },
    • "config": [
      • {
        • "docID": [
          • 0
          ],
        • "excludeAuthChecks": 2
        }
      ],
    • "log": true,
    • "logLevel": "FatalError",
    • "forceDocID": 0,
    • "matchTextFieldMask": true,
    • "fastDocDetect": true,
    • "updateOCRValidityByGlare": true,
    • "checkRequiredTextFields": true,
    • "returnCroppedBarcode": true,
    • "imageQa": {
      • "brightnessThreshold": 0,
      • "dpiThreshold": 0,
      • "angleThreshold": 0,
      • "focusCheck": true,
      • "glaresCheck": true,
      • "colornessCheck": true,
      • "moireCheck": true,
      • "documentPositionIndent": 0
      },
    • "respectImageQuality": true,
    • "forceDocFormat": 0,
    • "noGraphics": true,
    • "documentAreaMin": 0,
    • "depersonalizeLog": true,
    • "multiDocOnImage": true,
    • "shiftExpiryDate": 0,
    • "minimalHolderAge": 0,
    • "returnUncroppedImage": true,
    • "mrzFormatsFilter": [
      • "1x30"
      ],
    • "forceReadMrzBeforeLocate": true,
    • "parseBarcodes": true,
    • "convertCase": 0,
    • "splitNames": true,
    • "disablePerforationOCR": true,
    • "documentGroupFilter": [
      • 0
      ],
    • "processAuth": 0,
    • "deviceId": 0,
    • "deviceType": 0,
    • "deviceTypeHex": "string",
    • "ignoreDeviceIdFromImage": true,
    • "documentIdList": [
      • 0
      ],
    • "rfid": {
      • "paSensitiveCodesDisable": [
        • -1879048191
        ]
      },
    • "checkAuth": true,
    • "authParams": {
      • "checkLiveness": true,
      • "livenessParams": {
        • "checkOVI": true,
        • "checkMLI": true,
        • "checkHolo": true,
        • "checkED": true
        },
      • "checkUVLuminiscence": true,
      • "checkIRB900": true,
      • "checkImagePatterns": true,
      • "checkFibers": true,
      • "checkExtMRZ": true,
      • "checkExtOCR": true,
      • "checkAxial": true,
      • "checkBarcodeFormat": true,
      • "checkIRVisibility": true,
      • "checkIPI": true,
      • "checkPhotoEmbedding": true,
      • "checkPhotoComparison": true,
      • "checkLetterScreen": true
      },
    • "mrzDetectMode": 0
    },
  • "List": [
    • {
      • "light": 6,
      • "page_idx": 0,
      • "ImageData": {
        • "image": "<base64 image>"
        }
      }
    ],
  • "livePortrait": "Base64 encoded data",
  • "extPortrait": "Base64 encoded data",
  • "ContainerList": {
    • "Count": 0,
    • "List": [
      • {
        • "Status": {
          • "overallStatus": 0,
          • "optical": 0,
          • "portrait": 0,
          • "rfid": 0,
          • "stopList": 0,
          • "detailsRFID": {
            },
          • "detailsOptical": {
            }
          },
        • "buf_length": 0,
        • "light": 0,
        • "list_idx": 0,
        • "page_idx": 0,
        • "result_type": 0
        }
      ]
    },
  • "systemInfo": {
    • "license": "string",
    • "recaptcha_token": "string"
    },
  • "passBackObject": { }
}

Response samples

Content type
application/json
{
  • "ChipPage": 0,
  • "ProcessingFinished": 0,
  • "ContainerList": {
    • "Count": 0,
    • "List": [
      • {
        • "Status": {
          • "overallStatus": 0,
          • "optical": 0,
          • "portrait": 0,
          • "rfid": 0,
          • "stopList": 0,
          • "detailsRFID": {
            },
          • "detailsOptical": {
            }
          },
        • "buf_length": 0,
        • "light": 0,
        • "list_idx": 0,
        • "page_idx": 0,
        • "result_type": 0
        }
      ]
    },
  • "TransactionInfo": {
    • "ComputerName": "7cded6852d20",
    • "DateTime": "2020-05-27T08:17:03.247Z",
    • "TransactionID": "dc5eb444-ad6e-4ebc-8102-d62d5bb56a4e",
    • "UserName": "user"
    },
  • "log": "string",
  • "passBackObject": { },
  • "morePagesAvailable": 0,
  • "elapsedTime": 0
}

transaction

Preprocess

path Parameters
transactionId
required
integer <uuid>

Transaction id

Request Body schema: application/json
tag
string

session id

required
object (ProcessParams)
Array of objects (ProcessRequestImage)
livePortrait
string <base64>

Live portrait photo

extPortrait
string <base64>

Portrait photo from an external source

object (ContainerList)

List with various objects, containing processing results

object (ProcessSystemInfo)
object

Free-form object to be included in response. Must be object, not list or simple value. Do not affect document processing. Use it freely to pass your app params. Stored in process logs.

Responses

Response Schema: application/json
tag
string
transactionId
string <uuid>

Request samples

Content type
application/json
{
  • "tag": "string",
  • "processParam": {
    • "lcidFilter": [ ],
    • "lcidIgnoreFilter": [ ],
    • "oneShotIdentification": true,
    • "useFaceApi": true,
    • "faceApi": {},
    • "doDetectCan": true,
    • "imageOutputMaxHeight": 0,
    • "imageOutputMaxWidth": 0,
    • "scenario": "Mrz",
    • "resultTypeOutput": [
      • 1
      ],
    • "doublePageSpread": true,
    • "generateDoublePageSpreadImage": true,
    • "fieldTypesFilter": [
      • 0
      ],
    • "dateFormat": "MM/dd/yyyy",
    • "measureSystem": 0,
    • "imageDpiOutMax": 0,
    • "alreadyCropped": true,
    • "customParams": { },
    • "config": [
      • {
        • "docID": [
          • 0
          ],
        • "excludeAuthChecks": 2
        }
      ],
    • "log": true,
    • "logLevel": "FatalError",
    • "forceDocID": 0,
    • "matchTextFieldMask": true,
    • "fastDocDetect": true,
    • "updateOCRValidityByGlare": true,
    • "checkRequiredTextFields": true,
    • "returnCroppedBarcode": true,
    • "imageQa": {
      • "brightnessThreshold": 0,
      • "dpiThreshold": 0,
      • "angleThreshold": 0,
      • "focusCheck": true,
      • "glaresCheck": true,
      • "colornessCheck": true,
      • "moireCheck": true,
      • "documentPositionIndent": 0
      },
    • "respectImageQuality": true,
    • "forceDocFormat": 0,
    • "noGraphics": true,
    • "documentAreaMin": 0,
    • "depersonalizeLog": true,
    • "multiDocOnImage": true,
    • "shiftExpiryDate": 0,
    • "minimalHolderAge": 0,
    • "returnUncroppedImage": true,
    • "mrzFormatsFilter": [
      • "1x30"
      ],
    • "forceReadMrzBeforeLocate": true,
    • "parseBarcodes": true,
    • "convertCase": 0,
    • "splitNames": true,
    • "disablePerforationOCR": true,
    • "documentGroupFilter": [
      • 0
      ],
    • "processAuth": 0,
    • "deviceId": 0,
    • "deviceType": 0,
    • "deviceTypeHex": "string",
    • "ignoreDeviceIdFromImage": true,
    • "documentIdList": [
      • 0
      ],
    • "rfid": {
      • "paSensitiveCodesDisable": [
        • -1879048191
        ]
      },
    • "checkAuth": true,
    • "authParams": {
      • "checkLiveness": true,
      • "livenessParams": {
        • "checkOVI": true,
        • "checkMLI": true,
        • "checkHolo": true,
        • "checkED": true
        },
      • "checkUVLuminiscence": true,
      • "checkIRB900": true,
      • "checkImagePatterns": true,
      • "checkFibers": true,
      • "checkExtMRZ": true,
      • "checkExtOCR": true,
      • "checkAxial": true,
      • "checkBarcodeFormat": true,
      • "checkIRVisibility": true,
      • "checkIPI": true,
      • "checkPhotoEmbedding": true,
      • "checkPhotoComparison": true,
      • "checkLetterScreen": true
      },
    • "mrzDetectMode": 0
    },
  • "List": [
    • {
      • "light": 6,
      • "page_idx": 0,
      • "ImageData": {
        • "image": "<base64 image>"
        }
      }
    ],
  • "livePortrait": "Base64 encoded data",
  • "extPortrait": "Base64 encoded data",
  • "ContainerList": {
    • "Count": 0,
    • "List": [
      • {
        • "Status": {
          • "overallStatus": 0,
          • "optical": 0,
          • "portrait": 0,
          • "rfid": 0,
          • "stopList": 0,
          • "detailsRFID": {
            },
          • "detailsOptical": {
            }
          },
        • "buf_length": 0,
        • "light": 0,
        • "list_idx": 0,
        • "page_idx": 0,
        • "result_type": 0
        }
      ]
    },
  • "systemInfo": {
    • "license": "string",
    • "recaptcha_token": "string"
    },
  • "passBackObject": { }
}

Response samples

Content type
application/json
{
  • "tag": "string",
  • "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc"
}

Get preprocess transaction data

path Parameters
transactionId
required
integer <uuid>

Transaction id

Responses

Response Schema: application/json
transactionId
integer <uuid>
tag
string
object (OutData)
object (InData)

Response samples

Content type
application/json
{
  • "transactionId": 0,
  • "tag": "string",
  • "outData": {
    • "url": "string",
    • "images": [
      • {
        • "fieldType": 201,
        • "light": 0,
        • "listIdx": 0,
        • "pageIdx": 0,
        • "url": "string"
        }
      ]
    },
  • "inData": {
    • "video": {
      • "metadata": { },
      • "url": "string"
      },
    • "images": [
      • {
        • "fieldType": 201,
        • "light": 0,
        • "listIdx": 0,
        • "pageIdx": 0,
        • "url": "string"
        }
      ]
    }
}

Get preprocess transaction result

path Parameters
transactionId
required
integer <uuid>

Transaction id

query Parameters
withImages
boolean
Enum: true false

With base64 images or url

Responses

Response Schema: application/json
ChipPage
integer (RfidLocation)
Enum: 0 1 2

Determines the presence and location of an RFID chip in a document. 0 - no rfid chip; 1 - chip is located in the document data page; 2 - chip is located in the back page or inlay of the document

ProcessingFinished
integer (ProcessingStatus)
Enum: 0 1 2
object (ContainerList)

List with various objects, containing processing results

object (TransactionInfo)
log
string

Base64 encoded transaction processing log

object

Free-form object provided in request. See passBackObject property of ProcessRequest.

morePagesAvailable
integer
elapsedTime
integer

Time the document processing has taken, ms.

Response samples

Content type
application/json
{
  • "ChipPage": 0,
  • "ProcessingFinished": 0,
  • "ContainerList": {
    • "Count": 0,
    • "List": [
      • {
        • "Status": {
          • "overallStatus": 0,
          • "optical": 0,
          • "portrait": 0,
          • "rfid": 0,
          • "stopList": 0,
          • "detailsRFID": {
            },
          • "detailsOptical": {
            }
          },
        • "buf_length": 0,
        • "light": 0,
        • "list_idx": 0,
        • "page_idx": 0,
        • "result_type": 0
        }
      ]
    },
  • "TransactionInfo": {
    • "ComputerName": "7cded6852d20",
    • "DateTime": "2020-05-27T08:17:03.247Z",
    • "TransactionID": "dc5eb444-ad6e-4ebc-8102-d62d5bb56a4e",
    • "UserName": "user"
    },
  • "log": "string",
  • "passBackObject": { },
  • "morePagesAvailable": 0,
  • "elapsedTime": 0
}

Delete preprocess transactions by tag

path Parameters
tagId
required
integer <uuid>

Tag id

Responses

Response Schema: application/json
any

Response samples

Content type
application/json
null

Status Model

overallStatus
required
integer (CheckResult)
Enum: 0 1 2

0 - result is negative; 1 - result is positive; 2 - сheck was not performed

optical
required
integer (CheckResult)
Enum: 0 1 2

0 - result is negative; 1 - result is positive; 2 - сheck was not performed

portrait
integer (CheckResult)
Enum: 0 1 2

0 - result is negative; 1 - result is positive; 2 - сheck was not performed

rfid
integer (CheckResult)
Enum: 0 1 2

0 - result is negative; 1 - result is positive; 2 - сheck was not performed

stopList
integer (CheckResult)
Enum: 0 1 2

0 - result is negative; 1 - result is positive; 2 - сheck was not performed

object (detailsRFID)
required
object (detailsOptical)
{
  • "overallStatus": 0,
  • "optical": 0,
  • "portrait": 0,
  • "rfid": 0,
  • "stopList": 0,
  • "detailsRFID": {
    • "overallStatus": 0,
    • "AA": 0,
    • "BAC": 0,
    • "CA": 0,
    • "PA": 0,
    • "PACE": 0,
    • "TA": 0
    },
  • "detailsOptical": {
    • "overallStatus": 0,
    • "docType": 0,
    • "expiry": 0,
    • "imageQA": 0,
    • "mrz": 0,
    • "pagesCount": 0,
    • "security": 0,
    • "text": 0
    }
}

Text Model

status
required
integer (CheckResult)
Enum: 0 1 2

0 - result is negative; 1 - result is positive; 2 - сheck was not performed

validityStatus
required
integer (CheckResult)
Enum: 0 1 2

0 - result is negative; 1 - result is positive; 2 - сheck was not performed

comparisonStatus
required
integer (CheckResult)
Enum: 0 1 2

0 - result is negative; 1 - result is positive; 2 - сheck was not performed

required
Array of objects (TextField)
required
Array of objects (TextAvailableSource)
{
  • "status": 0,
  • "validityStatus": 0,
  • "comparisonStatus": 0,
  • "fieldList": [
    • {
      • "fieldType": 0,
      • "fieldName": "string",
      • "lcid": 0,
      • "status": 0,
      • "validityStatus": 0,
      • "comparisonStatus": 0,
      • "value": "string",
      • "valueList": [
        • {
          • "source": "MRZ",
          • "value": "string",
          • "originalValue": "string",
          • "originalSymbols": [
            ],
          • "pageIndex": 0,
          • "probability": 100,
          • "fieldRect": {
            },
          • "rfidOrigin": {
            }
          }
        ],
      • "validityList": [
        • {
          • "source": "MRZ",
          • "status": 0
          }
        ],
      • "comparisonList": [
        • {
          • "sourceLeft": "MRZ",
          • "sourceRight": "MRZ",
          • "status": 0
          }
        ]
      }
    ],
  • "availableSourceList": [
    • {
      • "source": "MRZ",
      • "validityStatus": 0,
      • "containerType": 0
      }
    ]
}

Images Model

Images model:

required
Array of objects (ImagesAvailableSource)
required
Array of objects (ImagesField)
{
  • "availableSourceList": [
    • {
      • "containerType": 0,
      • "source": "MRZ"
      }
    ],
  • "fieldList": [
    • {
      • "fieldName": "string",
      • "fieldType": 201,
      • "valueList": [
        • {
          • "source": "MRZ",
          • "value": "Base64 encoded image",
          • "originalValue": "Base64 encoded image",
          • "originalPageIndex": 0,
          • "pageIndex": 0,
          • "lightIndex": 0,
          • "containerType": 0,
          • "fieldRect": {
            },
          • "rfidOrigin": {
            }
          }
        ]
      }
    ]
}

Document image model:

image
required
string <base64> (ImageBase64)

Base64 encoded image

{
  • "image": "Base64 encoded image"
}

Document Model

Choosen Document model:

DocumentName
string

Document name

ID
integer

Unique document type template identifier (Regula's internal numeric code)

P
number [ 0 .. 1 ]

A measure of the likelihood of correct recognition in the analysis of this type of document

RFID_Presence
integer (RfidLocation)
Enum: 0 1 2

Determines the presence and location of an RFID chip in a document. 0 - no rfid chip; 1 - chip is located in the document data page; 2 - chip is located in the back page or inlay of the document

object (FDSIDList)

Extended document type info and Regula's 'Information Reference Systems' links

NecessaryLights
integer

Combination of lighting scheme identifiers (Light enum) required to conduct OCR for this type of document

CheckAuthenticity
integer

Set of authentication options provided for this type of document (combination of Authenticity enum)

UVExp
integer

The required exposure value of the camera when receiving images of a document of this type for a UV lighting scheme

AuthenticityNecessaryLights
integer

Combination of lighting scheme identifiers (combination of Light enum) needed to perform all authenticity checks specified in CheckAuthenticity

{
  • "DocumentName": "string",
  • "ID": 0,
  • "P": 0.9913095831871032,
  • "RFID_Presence": 0,
  • "FDSIDList": {
    • "ICAOCode": "str",
    • "List": [
      • 0
      ],
    • "dType": 0,
    • "dFormat": 0,
    • "dMRZ": true,
    • "dDescription": "string",
    • "dYear": "string",
    • "dCountryName": "string",
    • "dStateCode": "string",
    • "dStateName": "string",
    • "isDeprecated": true
    },
  • "NecessaryLights": 0,
  • "CheckAuthenticity": 0,
  • "UVExp": 0,
  • "AuthenticityNecessaryLights": 0
}

Candidates model:

RecResult
integer (DocumentTypeRecognitionResult)
Enum: 0 15 29
Array of objects (OneCandidate)
{
  • "RecResult": 0,
  • "Candidates": [
    • {
      • "DocumentName": "string",
      • "ID": 0,
      • "P": 0.9913095831871032,
      • "RFID_Presence": 0,
      • "FDSIDList": {
        • "ICAOCode": "str",
        • "List": [
          • 0
          ],
        • "dType": 0,
        • "dFormat": 0,
        • "dMRZ": true,
        • "dDescription": "string",
        • "dYear": "string",
        • "dCountryName": "string",
        • "dStateCode": "string",
        • "dStateName": "string",
        • "isDeprecated": true
        },
      • "NecessaryLights": 0,
      • "CheckAuthenticity": 0,
      • "UVExp": 0,
      • "AuthenticityNecessaryLights": 0
      }
    ]
}

Authenticity Model

Type
required
integer (AuthenticityResultType)
Enum: 1 2 4 8 16 … 16 more
Result
required
integer (CheckResult)
Enum: 0 1 2

0 - result is negative; 1 - result is positive; 2 - сheck was not performed

required
Array of Security Feature Check (object) or Ident Check (object) or Fibers Check (object) or OCR Security Text Check (object) or Photo Ident Check (object)
{
  • "Type": 1,
  • "Result": 0,
  • "List": [
    • {
      • "Type": 0,
      • "ElementResult": 0,
      • "ElementDiagnose": 0,
      • "ElementType": 0,
      • "ElementRect": {
        • "left": 0,
        • "top": 0,
        • "right": 0,
        • "bottom": 0
        },
      • "Visibility": 0,
      • "CriticalFlag": 0,
      • "AreaList": {
        • "Count": 0,
        • "List": [
          • {
            }
          ],
        • "Points": [
          • {
            }
          ]
        },
      • "Reserved2": 0
      }
    ]
}