/validation/

POST https://api.scandoc.ai/ss/validation/

Validation method is desinged to be used in real-time to validate or invalidate images before submitting them to extraction

Validation procedure requires a fresh access token, check out our authenticate section.

The validation procedure checks image quality in multiple steps:

• By checking image blurriness
• By checking image resolution
• By checking if the image is supported by the service
• By checking image position relative to the camera (if it is centered and sufficiently close to the camera)
• By checking image rotation relative to the camera (if it is rotated)

All the given parameters need to be checked before the image is sent to extraction to maximize performance. A pseudo-code regarding the validation procedure is given in the following manner:

Pseudocode

var image

do while image not validated 3 times in a row

	image <- capture image from video stream
	x, y <- image.shape()
	resizing_coef <- max(x, y) / 384
	xx, yy <- x / resizing_coef, y / resizing_coef
	
	resized_image <- image.resize(xx, yy)

	check_validity(resized_image)
		
end

results <- do_extraction(image) 

Images sent to the validation should be resized to a smaller size, that way we can improve response and network time. And the smaller images are usually sufficient in determining if the original image is suitable for extraction.

Request format

Validation is a POST method that requires a JSON body in the following format:

JSON

{
 "AcceptTermsAndConditions" : true ,
 "DataFields" : {
	 	"Images" : [
 			"<Base64-encoded-resized-image>"
 	 	],
    "BlurValues": [<BV1>, <BV2>, ...]
 },
	" Settings " : {}
}

The method supports sending multiple Base64 encoded images due to backwards compatibility, but we suggest you send only a single image per request. Accepting terms and conditions is neccessary since we are dealing with sensitive data and personal information. If you do not accept our terms and conditions, your request will be rejected.

Response format

Service responds in a JSON format in the following manner for a response status 200:

JSON

{
    "TransactionID":"<TRANSACTION-UUID>",
    "UploadedAt":"<TIMESTAMP>",
    "ProductName":"Scan App v<VERSION>",
    "Errors":["<ERROR1>", ...],
    "Warnings":["<WARNING1>", ...],
    "Status": <STATUS-CODE>,
    "Method":"Validation",
    "InfoCode":<INFO-CODE>,
    "Keypoints":
        [
            [<KEYPOINT1-x>, <KEYPOINT1-y>],
            [<KEYPOINT2-x>, <KEYPOINT2-y>],
            [<KEYPOINT3-x>, <KEYPOINT3-y>],
            [<KEYPOINT4-x>, <KEYPOINT4-y>]
        ],
    "DetectedBlurValue": <BV>,
    "Validated": <true/false>,
    "Index": <IMG-INDEX>,
    "Country": "<DOCUMENT-ISO-3166-1-ALPHA-3-COUNTRY-CODE>",
    "Side":"<FRONT/BACK>",
    "Series":"<ALPHA-3-COUNTRY-CODE>-<DOCUMENT-TYPE-IDENTIFIER>-<5-DIGIT-SERIES>",
    "DocType":"<ID/PASS/DL/RP>",
    "AnalysisTime": "<REQUEST-TIMING-IN-MS> ms"
}

Response keys in order are (bolded are important keys):

• TransactionID - UUID describing a transaction
• UploadedAt - timestamp of the transaction in the following format (iso format) - %Y-%m-%dT%H:%M:%S.%f
• ProductName - ScanApp version
• Errors - list of errors describing if some error occured (this is usually empty)
• Warnings - list of warnings if a warning occurred (this is usually empty)
• Status - response status code
• Method - Validation - constant
• InfoCode - see Validation info codes
• Keypoints - list of four float x, y coordinates in the range (0, 1) that point out four document corners (if detected) which you can use to create an animation where the system detects the document - keypoints are in the following order:
  1. top left
  2. top right
  3. bottom right
  4. bottom left
• Validated - if the image was successfully validated
• Index - if multiple images were submitted to the validation endpoint, returns the index of the best fit image (this can be ignored if you submit only a single image)
• Country - ISO 3 alpha country code
• Side - Front/Back depending which side was detected, important if the document has important data on the back side, see info code 1007 and two side document validation
• Series - ISO 3 alpha country code followed by FO (drivers licence), AO (passport), BO (ID card) or HO (residence permit) and the document series in a 5 digit format, example - USA-AO-10001 would be USA passport of 10001 series
• DocType - ID/PASS/RP/DL - constants
• AnalysisTime - request processing time in ms