REST API Reference

General

Version of the Document Validation server

GET /version

Version of the Document Validation server

Returns the version of document validation server.

Status Codes:

• 200 OK – OK

• 500 Internal Server Error – A server related error has occurred.

200 Response schema:

string

Example response:

HTTP/1.1 200 OK
Content-Type: text/plain

Aware Document Validation, version 1.0.0

500 Response schema:

Name	Type	Description
error	object
timestamp	string	The timestamp indicating when the error occurred.
status	integer	The status code associated with the error.
path	string	The API endpoint path that was called when the error occurred.
error	string	A short, human-readable classification of the error.
message	string	A detailed description of the error.

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain

{
    "timestamp": "2023-04-20T19:32:21.080+00:00",
    "status": 500,
    "error": "Internal Server Error",
    "message": "Error: Unexpected error occurred during processing"
}

Validation

Validates a document

POST /validate

Validates a document

Returns document fields, quality and validation status of the supplied document image or data groups.

Request schema:

The contents the encryptedDocument should be JSON returned by the capturing software. It should not be JSON embedded in a string.

Name	Type	Description
encryptedDocument	encryptedDocument	The encryptedDocument JSON that is returned from the Regula Mobile SDK
documentImages	(array of objects)
image	string	The base64 encoded document image.
transactionId	string	The transactionId returned by the Regula Mobile SDK.

Example request:

POST /validate HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "encryptedDocument": {},
    "documentImages": [
        {
            "image": "c3RyaW5n"
        }
    ],
    "transactionId": "string"
}

Status Codes:

• 200 OK – Successfully processed

• 400 Bad Request – An error related to the client request has occurred.

• 500 Internal Server Error – A server related error has occurred.

200 Response schema:

Name	Type	Description
images	images	Contains images captured or processed during validation.
quality	quality	Provides quality assessment results.
fields	object	Contains extracted data from the document.
overall	documentFields	The set of document field values after combining and verifying across all sources.
optical	documentFields	Fields extracted using OCR.
rfid	documentFields	Fields read from the RFID chip in the e-passport or ID, where available.
mrz	documentFields	Fields extracted from the Machine Readable Zone (MRZ) using parsing logic on the standardized text area.
security	security	Security check results.
info	info	General information about the document just as the document name.

Example response:

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

{
    "images": {
        "document": [
            {
                "image": "c3RyaW5n",
                "pageIndex": 1.0
            }
        ],
        "opticalPortrait": "c3RyaW5n",
        "rfidPortrait": "c3RyaW5n"
    },
    "quality": {
        "results": [
            {
                "glare": "PASS",
                "blur": "PASS",
                "resolution": "PASS",
                "color": "PASS",
                "perspective": "PASS",
                "bounds": "PASS",
                "pageIndex": 1.0
            }
        ]
    },
    "fields": {
        "overall": {
            "documentCode": "string",
            "issuingState": "string",
            "surname": "string",
            "givenName": "string",
            "documentNumber": "string",
            "nationality": "string",
            "dateOfBirth": {
                "year": 1.0,
                "month": 1.0,
                "day": 1.0,
                "text": "string"
            },
            "gender": "string",
            "dateOfExpiry": {
                "year": 1.0,
                "month": 1.0,
                "day": 1.0,
                "text": "string"
            },
            "personalNumber": "string",
            "optionalData1": "string",
            "optionalData2": "string"
        },
        "optical": {
            "documentCode": "string",
            "issuingState": "string",
            "surname": "string",
            "givenName": "string",
            "documentNumber": "string",
            "nationality": "string",
            "dateOfBirth": {
                "year": 1.0,
                "month": 1.0,
                "day": 1.0,
                "text": "string"
            },
            "gender": "string",
            "dateOfExpiry": {
                "year": 1.0,
                "month": 1.0,
                "day": 1.0,
                "text": "string"
            },
            "personalNumber": "string",
            "optionalData1": "string",
            "optionalData2": "string"
        },
        "rfid": {
            "documentCode": "string",
            "issuingState": "string",
            "surname": "string",
            "givenName": "string",
            "documentNumber": "string",
            "nationality": "string",
            "dateOfBirth": {
                "year": 1.0,
                "month": 1.0,
                "day": 1.0,
                "text": "string"
            },
            "gender": "string",
            "dateOfExpiry": {
                "year": 1.0,
                "month": 1.0,
                "day": 1.0,
                "text": "string"
            },
            "personalNumber": "string",
            "optionalData1": "string",
            "optionalData2": "string"
        },
        "mrz": {
            "documentCode": "string",
            "issuingState": "string",
            "surname": "string",
            "givenName": "string",
            "documentNumber": "string",
            "nationality": "string",
            "dateOfBirth": {
                "year": 1.0,
                "month": 1.0,
                "day": 1.0,
                "text": "string"
            },
            "gender": "string",
            "dateOfExpiry": {
                "year": 1.0,
                "month": 1.0,
                "day": 1.0,
                "text": "string"
            },
            "personalNumber": "string",
            "optionalData1": "string",
            "optionalData2": "string"
        }
    },
    "security": {
        "rfid": {
            "basicAccessControl": "PASS",
            "activeAuthentication": "PASS",
            "chipAuthentication": "PASS",
            "pace": "PASS",
            "passiveAuthentication": "PASS",
            "overall": "PASS"
        },
        "optical": {
            "overall": "PASS"
        },
        "overall": "PASS",
        "reasons": [
            "string"
        ]
    },
    "info": {
        "documentType": [
            {
                "name": "string",
                "pageIndex": 1.0
            }
        ]
    }
}

400 Response schema:

Name	Type	Description
error	object
timestamp	string	The timestamp indicating when the error occurred.
status	integer	The status code associated with the error.
path	string	The API endpoint path that was called when the error occurred.
error	string	A short, human-readable classification of the error.
message	string	A detailed description of the error.

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "timestamp": "2023-04-20T19:32:21.080+00:00",
    "status": 400,
    "error": "Bad Request",
    "message": "Error: Could not parse JSON"
}

500 Response schema:

Name	Type	Description
error	object
timestamp	string	The timestamp indicating when the error occurred.
status	integer	The status code associated with the error.
path	string	The API endpoint path that was called when the error occurred.
error	string	A short, human-readable classification of the error.
message	string	A detailed description of the error.

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain

{
    "timestamp": "2023-04-20T19:32:21.080+00:00",
    "status": 500,
    "error": "Internal Server Error",
    "message": "Error: Unexpected error occurred during processing"
}

Structure Reference

validateRequest Model Structure

Name	Type	Description
encryptedDocument	encryptedDocument	The encryptedDocument JSON that is returned from the Regula Mobile SDK
documentImages	(array of objects)
image	string	The base64 encoded document image.
transactionId	string	The transactionId returned by the Regula Mobile SDK.

encryptedDocument Model Structure

Freeform object

validateResponse Model Structure

Name	Type	Description
images	images	Contains images captured or processed during validation.
quality	quality	Provides quality assessment results.
fields	object	Contains extracted data from the document.
overall	documentFields	The set of document field values after combining and verifying across all sources.
optical	documentFields	Fields extracted using OCR.
rfid	documentFields	Fields read from the RFID chip in the e-passport or ID, where available.
mrz	documentFields	Fields extracted from the Machine Readable Zone (MRZ) using parsing logic on the standardized text area.
security	security	Security check results.
info	info	General information about the document just as the document name.

security Model Structure

Name	Type	Description
rfid	rfidSecurity	Security validation results from the RFID chip, including cryptographic checks like BAC, AA, CA, PACE, and Passive Authentication.
optical	opticalVerification	Results of optical security feature verification.
overall	checkValue	The combined result of all security checks (RFID and optical), representing the overall document authenticity confidence.
reasons	(array of string)	A list of reasons for the security failure.

opticalVerification Model Structure

Name	Type	Description
overall	checkValue	Indicates whether the optical verification checks passed.

documentFields Model Structure

Name	Type	Description
documentCode	string	The document code, usually one or two characters. Common values: ‘P’ for Passport, ‘ID’ for Identity Card.
issuingState	string	The country or organization that issued the document, typically represented by a three-letter ICAO code.
surname	string	The primary identifier (surname) of the document holder.
givenName	string	The secondary identifiers (given names) of the document holder.
documentNumber	string	The document number from the ID document.
nationality	string	The nationality of the document holder, typically a three-letter ICAO country code.
dateOfBirth	dateValue	The date of birth of the document holder.
gender	string	The gender of the document holder, represented by a single character: ‘M’, ‘F’, or ‘<’ if unspecified.
dateOfExpiry	dateValue	The expiry date of the document.
personalNumber	string	Optional field used by issuing agencies to store national or personal identity number.
optionalData1	string	Additional optional data field.
optionalData2	string	Additional optional data field.

images Model Structure

Name	Type	Description
document	documentImages
opticalPortrait	string	Portrait image extracted optically from the document.
rfidPortrait	string	Portrait image extracted from the RFID chip.

info Model Structure

Name	Type	Description
documentType	(array of objects)
name	string	Name of the document type detected.
pageIndex	number	Index of the document page.

quality Model Structure

Name	Type	Description
results	(array of objects)
glare	string	Checks whether the image is glare is present in the image. Values: PASS, FAIL, NOT_PERFORMED, NOT_SUPPORTED
blur	string	Checks whether the image is blurry. Values: PASS, FAIL, NOT_PERFORMED, NOT_SUPPORTED
resolution	string	Checks whether the image has adequate resolution. Values: PASS, FAIL, NOT_PERFORMED, NOT_SUPPORTED
color	string	Checks whether the image has color. Values: PASS, FAIL, NOT_PERFORMED, NOT_SUPPORTED
perspective	string	Checks whether the image perspective is in range. Values: PASS, FAIL, NOT_PERFORMED, NOT_SUPPORTED
bounds	string	Checks whether the image fully contains the document. Values: PASS, FAIL, NOT_PERFORMED, NOT_SUPPORTED
pageIndex	number

rfidSecurity Model Structure

Name	Type	Description
basicAccessControl	checkValue	Indicates the result of Basic Access Control (BAC), which protects the communication channel between the chip and reader using a key derived from the MRZ.
activeAuthentication	checkValue	Result of Active Authentication (AA), which detects cloned chips by verifying the chip’s private key via a challenge-response protocol.
chipAuthentication	checkValue	Result of Chip Authentication (CA), which ensures the chip is genuine and creates a secure communication channel by establishing session keys.
pace	checkValue	Result of Password Authenticated Connection Establishment (PACE), a stronger replacement for BAC that protects the chip-reader communication.
passiveAuthentication	string	Indicates the result of Passive Authentication (PA), which verifies the integrity and authenticity of data on the chip by validating the digital signatures in the Document Security Object (SOD). Values: PASS, FAIL, NOT_PERFORMED, NOT_SUPPORTED, incorrectDsCertificate
overall	checkValue	Aggregate result summarizing the outcome of all RFID security mechanisms performed.

documentImages Model Structure

Name	Type	Description
documentImages	(array of objects)
image	string	The base64 encoded document image.
pageIndex	number	An integer indicating the page number of the document.

dateValue Model Structure

Name	Type	Description
year	number	The four-digit year parsed from the date string.
month	number	The numeric month (1–12) parsed from the date string.
day	number	The numeric day (1–31) parsed from the date string.
text	string	The raw date string as it appears on the document.

checkValue Model Structure

Name	Type	Description
checkValue	string	Values: PASS, FAIL, NOT_PERFORMED, NOT_SUPPORTED

error Model Structure

Name	Type	Description
timestamp	string	The timestamp indicating when the error occurred.
status	integer	The status code associated with the error.
path	string	The API endpoint path that was called when the error occurred.
error	string	A short, human-readable classification of the error.
message	string	A detailed description of the error.