ID international

1. Service description

The ID international service allows to validate different type of official identification documents. This service process images, verifying it's authenticity and respond with information about the document.

2. Image requirements

Below are the requirements for size and quality of document images captured by any device, which are necessary for successful image processing by ID international service:

Good lighting

Environment with good lighting helps with recognizing the characters in the image. When the image is too dark or too bright the document can not be validated.

IMG_GoodLigthing

Avoid reflections

Don't use flashlight on your device. Avoid reflections from lamps or environmental lights.

IMG_Avoidreflections

Focus and sharpness

Make sure the image is clear and there are no blurred areas.

IMG_focusandsharpnes

Angle

The tilt angle of the document should not exceed 10 degrees in any direction (horizontal or vertical).

IMG_angle

Margins (too close)

Make sure there's minimum space around the document. Don't zoom the image. It is recommended that the document takes up 70-80% of the image.

IMG_margins

Margins (too far)

Make sure the space around the document is not taking more than 20-30% of the image It is recommended that the document takes up 70-80% of the image.

IMG_marginstoofar

Contrast

The document should be in clear contrast to the background. A light-colored document on a light background, as well as a dark-colored document on a dark background, cannot be recognized.

IMG_constrast

Resolution of the image

To achieve good quality of recognition of identification documents, we recommend that you provide images captured by camera with a resolution of at least Full HD (1920×1080) and autofocus.

IMG_resolution

Subjection

Make sure your hands or other objects don't cover document data.

IMG_subjection

3. API Specification

Request squema

URL

POST ~/api/IDInternational/validateIdentification

Parameters

Tag	Type	Required	Description
FrontID	file	yes	Support jpg, jpeg or png images.
BackID	file	no	Support jpg, jpeg or png images.

Headers

Tag	Type	Required	Description
ApiKey	string	yes	Customer key.

Response squema

Status

Name	Type	Description
valid	String	true / false
containerlist	Array
warnings	Array	code:
.	.	message:

{
  "valid": false,
  "containerlist": [],
  "warnings": [
     {
      "code": "IDN110",
      "message": "DocType result is negative"
    },
     {
      "code": "IDN111",
      "message": "Expiry result is negative"
    },
     {
      "code": "IDN112",
      "message": "ImageQA result is negative"
    },
     {
      "code": "IDN113",
      "message": "Mrz result is negative"
    },
     {
      "code": "IDN115",
      "message": "Security result is negative"
    },
     {
      "code": "IDN116",
      "message": "Text result is negative"
    },
    {
      "code": "IDN210",
      "message": "DocType сheck was not performed"
    },
    {
      "code": "IDN211",
      "message": "Expiry сheck was not performed"
    },
    {
      "code": "IDN212",
      "message": "ImageQA сheck was not performed"
    },
    {
      "code": "IDN213",
      "message": "Mrz сheck was not performed"
    },
    {
      "code": "IDN215",
      "message": "Security сheck was not performed"
    },
    {
      "code": "IDN216",
      "message": "Text сheck was not performed"
    }
  ]
}

ContainerList

The list of containers that stores results formed during the document processing.

ContainerList
├── Count
├── List
│   ├── AuthenticityCheckList
│   │   └── ...
│   ├── DocumentPosition 
│   │   └── ...
│   ├── OneCandidate 
│   │   └── ...
│   ├──  DocVisualExtendedInfo
│   │   └── ...
│   ├── DocGraphicsInfo
│   │   └── ...
│   ├── ImageQualityCheckList
│   │   └── ...
│   ├──ListVerifiedFields
│   │   └── ...
│   ├── Text
│   │   └── ...
│   ├── Images
│   │   └── ...
│   ├── Status
│   │   └── ...
│   ├── MrzPosition 
│   │   └── ...
│   ├──  DocBarCodeInfo
│   │   └── ...
│   ├── MRZTestQuality
│   │   └── ...
│   ├── ResultMRZDetector
│   │   └── ...
│   ├── FaceDetection
│   │   └── ...
│   ├── RawImageContainer
│   │   └── ...

Container	Result type	Description
AuthenticityCheckList	20	Stores the results of performing different document authenticity checks.
DocumentPosition	85	Stores the document position information.
OneCandidate	9	Stores the document type information.
DocVisualExtendedInfo	3	Stores text results of MRZ.
DocGraphicsInfo	6	Stores graphic results of document filling area and barcodes reading.
ImageQualityCheckList	30	Stores the results of performing different image quality checks.
ListVerifiedFields	15	Stores the results of comparing the MRZ text data, document filling area data, barcodes data and data retrieved from RFID-chip.
Text	36	Stores the text results.
Images	37	Stores the graphic results.
Status	33	Stores the statuses of the document verification.
MrzPosition	61	Stores the MRZ position information.
DocBarCodeInfo	5	Stores results of barcodes areas search on the scanned document page and their reading in binary non-formatted code.
MRZTestQuality	7	Stores the information on document MRZ printing quality check results.

DocumentPosition

DocumentPosition
├── Angle
├── Center
│   ├── x
│   └── y
├── Dpi
├── Height
├── Inverse
├── LeftBottom
│   ├── x
│   └── y
├── LeftTop
│   ├── x
│   └── y
├── ObjArea
├── ObjIntAngleDev
├── PerspectiveTr
├── ResultStatus
├── RightBottom
│   ├── x
│   └── y
├── RightTop
│   ├── x
│   └── y
├── Width
└── docFormat

Parameter	Description
Angle	The document rotation angle.
Center	The document center coordinates.
Dpi	Resolution in dots per inch.
Height	The document height.
Inverse	Internal use parameter.
LeftBottom	The document left bottom corner coordinates.
LeftTop	The document left top corner coordinates.
ObjArea	Internal use parameter.
ObjIntAngleDev	Internal use parameter.
PerspectiveTr	Internal use parameter.
ResultStatus	Internal use parameter.
RightBottom	The document right bottom corner coordinates.
RightTop	The document right top corner coordinates.
Width	The document width.
docFormat	The document format.

OneCandidate

OneCandidate
├── AuthenticityNecessaryLights
├── CheckAuthenticity
├── DocumentName
├── FDSIDList
│   ├── Count
│   ├── ICAOCode
│   ├── List
│   ├── dCountryName
│   ├── dFormat
│   ├── dMRZ
│   ├── dType
│   └── dYear
├── ID
├── NecessaryLights
├── OVIExp
├── P
├── RFID_Presence
├── Rotated180
├── RotationAngle
└── UVExp

Parameter	Description
AuthenticityNecessaryLights	The combination of identifiers ofnecessary lighting schemes to performauthenticity check for the givendocument type.
CheckAuthenticity	Set of authenticity check optionsprovided for the given document type.
DocumentName	The document type name.
FDSIDList	Additional document information andits link to IRS document(s).
FDSIDList.Count	Number of elements in the array.
FDSIDList.ICAOCode	The document issuing country ICAOCode.
FDSIDList.List	The array of IRS document identifiers.
FDSIDList.dCountryName	The name of the country that issuedthe document.
FDSIDList.dFormat	The document format.
FDSIDList.dMRZ	A flag for MRZ presence on thedocument.
FDSIDList.dType	The document type.
FDSIDList.dYear	The year the document was issued.
ID	The document type numeric code.
NecessaryLights	The combination of identifiers ofnecessary lighting schemes to performOCR for the given document type.
OVIExp	The camera exposure value necessarywhen obtaining document images of thegiven type for AXIAL lighting scheme.
P	Estimation of correct recognitionprobability when analyzing the givendocument type.
RFID_Presence	Presence of RFID-chip in the document.
Rotated180	True if the document of the given typeis rotated by 180 degrees.
UVExp	The camera exposure value necessarywhen obtaining document images of thegiven type for UV lighting scheme.

ImageQualityCheckList

ImageQualityCheckList
├── Count
├── List
│   ├── areas
│   │   ├── Count
│   │   ├── List
│   │   │   ├── bottom
│   │   │   ├── left
│   │   │   ├── right
│   │   │   └── top
│   │   └── Points
│   ├── featureType
│   ├── mean
│   ├── probability
│   ├── result
│   ├── std_dev
│   └── type
└── result

Parameter	Description
Count	The number of results in the array.
List	The list of single check result pointers.
List.areas	Anomalous image areas.
List.featureType	The area examined.
List.mean	The check mean value.
List.probability	The check probability.
List.result	The check result.
List.std_dev	The check deviation.
List.type	The check result type.
result	The overall check result.

Text

Text
├── availableSourceList
│   ├── containerType
│   ├── source
│   └── validityStatus
├── comparisonStatus
├── dateFormat
├── fieldList
│   ├── comparisonList
│   ├── comparisonStatus
│   ├── fieldName
│   ├── fieldType
│   ├── lcid
│   ├── lcidName
│   ├── status
│   ├── validityList
│   │   ├── source
│   │   └── status
│   ├── validityStatus
│   ├── value
│   ├── valueList
│   │   ├── containerType
│   │   ├── fieldRect
│   │   │   ├── bottom
│   │   │   ├── left
│   │   │   ├── right
│   │   │   └── top
│   │   ├── originalSymbols
│   │   │   ├── code
│   │   │   ├── probability
│   │   │   ├── rect
│   │   │   │   ├── bottom
│   │   │   │   ├── left
│   │   │   │   ├── right
│   │   │   │   └── top
│   │   ├── originalValidity
│   │   ├── pageIndex
│   │   ├── probability
│   │   ├── source
│   │   └── value
├── status
└── validityStatus

Parameter	Description
availableSourceList	The list of available sources.
availableSourceList.containerType	The source type, integer representation, one of the Result.
availableSourceList.source	The source name, string representation.
availableSourceList.validityStatus	The verification result.
comparisonStatus	The comparison result.
dateFormat	The date format.
fieldList	The list of available text fields.
fieldList.comparisonList	The list of available comparisons in the given text field.
fieldList.comparisonStatus	The comparison status in the given text field.
fieldList.fieldName	The text field name, string representation.
fieldList.fieldType	The text field type, integer representation.
fieldList.lcid	The LCID type, integer representation.
fieldList.lcidName	The LCID name, string representation.
fieldList.status	The overall result of the given text field that combines comparsion and verification results.
fieldList.validityList	The list of verification results.
fieldList.validityStatus	The verification result of the text field.
fieldList.value	The single text field value.
fieldList.valueList	The list of all available values in the given text field.
fieldList.valueList.containerType	The source typ of the value, integer representation, one of the Result.
fieldList.valueList.fieldRect	The text field value rectangular area coordinates on the image.
fieldList.valueList.originalSymbols	Original symbols.
fieldList.valueList.originalValidity	Original validity.
fieldList.valueList.pageIndex	The page index.
fieldList.valueList.probability	The symbol recognition probability.
fieldList.valueList.source	The source name of the value, string representation.
fieldList.valueList.value	The single text field value.
status	The overall result of all available text fields that combines comparsion and verification results.
validityStatus	The overall verification result of all available text fields.

Images

Images
├── availableSourceList
│   ├── containerType
│   └── source
├── fieldList
│   ├── fieldName
│   ├── fieldType
│   ├── valueList
│   │   ├── containerType
│   │   ├── fieldRect
│   │   │   ├── bottom
│   │   │   ├── left
│   │   │   ├── right
│   │   │   └── top
│   │   ├── lightIndex
│   │   ├── originalPageIndex
│   │   ├── pageIndex
│   │   ├── source
│   │   └── value

Parameter	Description
availableSourceList	The list of available sources.
availableSourceList.containerType	The source type, integer representation, one of the Result.
availableSourceList.source	The source name, string representation.
fieldList	The list of available graphic fields.
fieldList.fieldName	The graphic field name, string representation.
fieldList.fieldType	The graphic field type, integer representation.
fieldList.valueList	The list of graphic field values.
fieldList.valueList.containerType	The source type which the value belongs to, integer representation.
fieldList.valueList.fieldRect	The field rectangular area coordinates on the image.
fieldList.valueList.lightIndex	The lightning scheme.
fieldList.valueList.originalPageIndex	Original page index.
fieldList.valueList.pageIndex	The page index.
fieldList.valueList.source	The source name which the value belongs to, string representation.
fieldList.valueList.value	The image value, Base64 format.

Status

Status
├── detailsOptical
│   ├── docType
│   ├── expiry
│   ├── imageQA
│   ├── mrz
│   ├── overallStatus
│   ├── pagesCount
│   ├── security
│   ├── text
│   └── vds
├── detailsRFID
│   ├── AA
│   ├── BAC
│   ├── CA
│   ├── PA
│   ├── PACE
│   ├── TA
│   └── overallStatus
├── optical
├── overallStatus
├── portrait
├── rfid
└── stopList

Parameter	Description
detailsOptical.docType	The check status if document type was recognized or not.
detailsOptical.expiry	The document validity period verification status.
detailsOptical.imageQA	The input images quality verification status.
detailsOptical.mrz	MRZ verification: values validity, dates, checkdigits verification.
detailsOptical.overallStatus	The summary of all optical results.
detailsOptical.pagesCount	The number of scanned document pages, integer.
detailsOptical.security	The authenticity verification status.
detailsOptical.text	Text fields valitity: values validity for specific fields, cross-comparison of values from different sources, dates & checkdigits verification.
detailsOptical.vds	The Visible Digital Seal verification status.
detailsRFID.AA	The active authentication status.
detailsRFID.BAC	The basics access control status.
detailsRFID.CA	The chip authentication status.
detailsRFID.PA	The passive authentication status.
detailsRFID.PACE	The password authenticated connection establishment status.
detailsRFID.TA	The terminal authentication status.
detailsRFID.overallStatus	The summary of all RFID results.
optical	The summary of all optical results. Same as detailsOptical.overallStatus.
overallStatus	The summary of all results.
portrait	The comparison status for portrait in the document against the live or external image.
rfid	The summary of all RFID results. Same as detailsRFID.overallStatus.
stopList	The verification status for the document data against the database.

MrzPosition

MrzPosition
├── Angle
├── Center
│   ├── x
│   └── y
├── Dpi
├── Height
├── Inverse
├── LeftBottom
│   ├── x
│   └── y
├── LeftTop
│   ├── x
│   └── y
├── ObjArea
├── ObjIntAngleDev
├── PerspectiveTr
├── ResultStatus
├── RightBottom
│   ├── x
│   └── y
├── RightTop
│   ├── x
│   └── y
├── Width
└── docFormat

Parameter	Description
Angle	The document rotation angle.
Center	The document center coordinates.
Dpi	Resolution in dots per inch.
Height	The document height.
Inverse	Internal use parameter.
LeftBottom	Document left bottom corner coordinates.
LeftTop	Document left top corner coordinates.
ObjArea	Internal use parameter.
ObjIntAngleDev	Internal use parameter.
PerspectiveTr	Internal use parameter.
ResultStatus	Internal use parameter.
RightBottom	The document right bottom corner coordinates.
RightTop	The document right top corner coordinates.
Width	The document width.
docFormat	The document format.