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	Time of error.
status	integer	Error status code.
path	string	Endpoint path.
error	string	Error type.
message	string	Detailed error description.

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
documentImages	inputDocumentImages

Example request:

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

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

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
quality	quality
fields	object
overall	documentFields
optical	documentFields
rfid	documentFields
mrz	documentFields
security	security
info	info

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": "c3RyaW5n",
                "pageIndex": 1.0
            }
        ]
    }
}

400 Response schema:

Name	Type	Description
error	object
timestamp	string	Time of error.
status	integer	Error status code.
path	string	Endpoint path.
error	string	Error type.
message	string	Detailed error description.

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	Time of error.
status	integer	Error status code.
path	string	Endpoint path.
error	string	Error type.
message	string	Detailed error description.

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
documentImages	inputDocumentImages

encryptedDocument Model Structure

Freeform object

validateResponse Model Structure

Name	Type	Description
images	images
quality	quality
fields	object
overall	documentFields
optical	documentFields
rfid	documentFields
mrz	documentFields
security	security
info	info

security Model Structure

Name	Type	Description
rfid	rfidSecurity
optical	opticalVerification
overall	checkValue
reasons	(array of string)	A list of reasons for the security failure

opticalVerification Model Structure

Name	Type	Description
overall	checkValue

documentFields Model Structure

Name	Type	Description
documentCode	string
issuingState	string
surname	string
givenName	string
documentNumber	string
nationality	string
dateOfBirth	dateValue
gender	string
dateOfExpiry	dateValue
personalNumber	string
optionalData1	string
optionalData2	string

images Model Structure

Name	Type	Description
document	documentImages
opticalPortrait	string
rfidPortrait	string

info Model Structure

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

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
activeAuthentication	checkValue
chipAuthentication	checkValue
pace	checkValue
passiveAuthentication	string	Values: PASS, FAIL, NOT_PERFORMED, NOT_SUPPORTED, incorrectDsCertificate
overall	checkValue

documentImages Model Structure

Name	Type	Description
documentImages	(array of objects)
image	string
pageIndex	number

inputDocumentImages Model Structure

Name	Type	Description
inputDocumentImages	(array of objects)
image	string

dateValue Model Structure

Name	Type	Description
year	number
month	number
day	number
text	string

checkValue Model Structure

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

error Model Structure

Name	Type	Description
timestamp	string	Time of error.
status	integer	Error status code.
path	string	Endpoint path.
error	string	Error type.
message	string	Detailed error description.