Submit the Person's Information from the ID Document

/aivpersonidtfy

Method : POST
URL : https://xxx.finexusgroup.com/AIV/rest/v1/aivpersonidtfy

info

This method allows the submission of a request to check authenticity of ID document based on the submitted image and extract the person’s information from the ID document.

The response will include:

• The assessment whether the ID document’s image is that of a genuine document based the various landmark checks and if the document is considered authentic
• It will return all information that can be extracted from the document.

Request

Request Parameters

Field Name	Required	Type	Description	Example
sourceInfo	Yes	Object	Source information.	Refer to explanation below.
interactionMode	Yes	Object	Interaction mode.	Refer to explanation below.
language	Optional	String	Language.	"en"
device	Optional	Object	Device information.	Refer to explanation below.
idType	Yes	String	ID type.	"mykad"
idNo	Yes	String	ID number.	"97XXXXXXXXXX"
nationality	Yes	String	Nationality.	"MY"
fullName	Yes	String	Full name.	"Wong XXX XXX"
idImage	Yes	Object	ID image.	Refer to explanation below.

Object: sourceInfo

Field Name	Required	Type	Description	Example
source	Yes	String	Source.	"FNXCRDS"
partnerId	Yes	String	Partner ID.	"BSSS"
productType	Optional	String	Partner type.	"appTest"
reference	Yes	String	Reference.	"2003160192931"
apiVersion	Yes	String	API version.	"1.6"
apiKey	Conditional	String	API key.	"123-KEJRU-001"
userId	Optional	String	User ID.	"mkchan"
userToken	Optional	String	User token.	"APPOKJSID8J1234"

Object: interactionMode

Field Name	Required	Type	Description	Example
mode	Yes	String	Mode.	"SYNC"
callbackUrl	Optional	String	Callback URL.

Object: device

Field Name	Required	Type	Description	Example
brand	Yes	String	Brand of the device.	"Vivo"
model	Yes	String	Model of the device.	"vivo 2005"
imei	Optional	Number	International Mobile Equipment Identity number.	"890077890908976"
mac	Optional	String	Media Access Control address.	"00:11:22:33:44:55"

Object: idImage

Field Name	Required	Type	Description	Example
imageFront	Yes	Object	Front image content of the ID document.	Refer to explanation below.
imageBack	Conditional	Object	Back image content of the ID document.	Refer to explanation below.

Object: imageFront

Field Name	Required	Type	Description	Example
contentEncoding	Yes	String	Encoding format of the image.	"base64"
contentMediaType	Yes	String	Media type of the image data.	"jpeg"
image	Yes	String	Entire image data.	"/9j/4AAQSkZJRgABAQ"

Object: imageBack

Field Name	Required	Type	Description	Example
contentEncoding	Yes	String	Encoding format of the image.	"base64"
contentMediaType	Yes	String	Media type of the image data.	"jpeg"
image	Yes	String	Entire image data.	"/9j/4AAQSkZJRgABAQ"

Response

Response Codes

Response Code	Description	Response Schema
200	The service is able to authenticate and allow the caller to use the service and method.	AIVPersonIdtfyPostResponse
400	Bad request whereby the service cannot find the message layout as expected.	N/A
401	Unauthorised access - unable to authenticate source system	N/A
405	Forbidden access - source system is not authorised to perform an action	N/A

Response Parameters

Field Name	Required	Type	Description	Example
status	Yes	Object	Status.	Refer to explanation below.
payload	Optional	Object	Information from the authenticity check.	Refer to explanation below.

Object: status

Field Name	Required	Type	Description	Example
sourceInfo	Yes	Object	Source information.	Refer to explanation below.
status	Yes	String	Status.	"SUCCESS"
errorList	Yes	Object	Error list.	Refer to explanation below.

Object: sourceInfo

Field Name	Required	Type	Description	Example
source	Yes	String	Source.	"FNXCRDS"
partnerId	Yes	String	Partner ID.	"BSSS"
productType	Optional	String	Partner type.	"appTest"
reference	Yes	String	Reference.	"2003160192931"
apiVersion	Yes	String	API version.	"1.6"
apiKey	Conditional	String	API key.	"123-KEJRU-001"
userId	Optional	String	User ID.	"mkchan"
userToken	Optional	String	User token.	"APPOKJSID8J1234"

Object: errorList

Field Name	Required	Type	Description	Example
msgCode	Yes	String	Message code.	"000"
msgText	Yes	String	Message text.

Object: payload

Field Name	Required	Type	Description	Example
landmark	Yes	Object	Landmark.	Refer to explanation below.
aivRefId	Yes	String	AIV reference ID.	"205"
idType	Optional	String	ID type.	"mykad"
extractedData	Optional	Object	Information extracted from a MyKad or passport image.	Refer to explanation below.
possibleFraud	Yes	String	Possible fraud.	"t"
qualityOfIdImage	Yes	String	Quality of ID image.	"t"
insufficientLandmarkDetection	Yes	String	Insufficient landmark detection.	"t"
recommendation	Yes	Object	Recommendation.	Refer to explanation below.

Object: landmark

Field Name	Required	Type	Description	Example
landmarkResult	Yes	Object	ID document's landmarks check results.	Refer to explanation below.
landmarkDetails	Yes	Object	Result of landmarks checking for MyKad or passport ID document.	Refer to explanation below.

Object: landmarkResult

Field Name	Required	Type	Description	Example
totalNo	Yes	Number	Total number of landmarks defined.	"10"
matchedNo	Yes	Number	Number of matched landmarks.	"0"
threshold	Yes	Number	Number of matched thresholds to be considered genuine image of ID document.	"4"
authenticityFlg	Yes	String	Authenticity flag.	"F"

Object: landmarkDetails (For MyKad)

Field Name	Required	Type	Description	Example
citizenFlg	Yes	String	Citizen flag.	"t"
icPlateMatch	Yes	String	Identification card plate match.	"t"
myKadLogoMatch	Yes	String	Mykad logo match.	"t"
myFlagMatch	Yes	String	Malaysian flag match.	"t"
ghostMatch	Yes	String	Potrait image match.	"t"
coatOfArmsMatch	Yes	String	Coat of arm logo match.	"t"
TnGLogoMatch	Yes	String	TnG logo match.	"t"
chipLogoMatch	Yes	String	Chip logo match.	"t"
ketuaPengarahTextFound	Yes	String	Ketua Pengarah text match.	"t"
genderMatch	Yes	String	Gender match.	"t"
validBirthYear	Yes	String	Valid birth year.	"t"

Object: landmarkDetails (For Passport)

Field Name	Required	Type	Description	Example
documentTypeMatch	Yes	String	Document type match.	"t"
issuingStateCodeMatch	Yes	String	Issuing state code match.	"t"
passportNoMatch	Yes	String	Passport number match.	"t"
expiredDocument	Yes	String	Expired document.	"t"
validMrz	Yes	String	Valid machine-readable zone.	"t"
primaryNameMatch	Optional	String	Primary name match.	"t"
secondaryNameMatch	Optional	String	Secondary name match.	"t"
dateOfBirthMatch	Optional	String	Date of birth match.	"t"
dateOfExpiryMatch	Optional	String	Date of expiry match.	"t"

Object: extractedData (For MyKad)

Field Name	Required	Type	Description	Example
myKadNo	Yes	String	MyKad number.	"890221-58-9666"
fullName	Yes	String	Full name.	"John Smith"
address	Yes	Object	Address.	Refer to explanation below.
gender	Yes	String	Gender.	"M"
placeOfBirth	Yes	String	Place of birth.	"Kuala Lumpur"
holderImage	Yes	Object	Face image of the MyKad holder.	Refer to explanation below.
muslimFlg	Yes	String	Muslim flag.	"t"

Object: address

Field Name	Required	Type	Description	Example
addrLine1	Yes	String	Address line 1.	"5, Jalan 3"
addrLine2	Optional	String	Address line 2.	"Sea Park"
addrLine3	Optional	String	Address line 3.
city	Yes	String	City.	"Petaling Jaya"
state	Yes	String	State.	"Selangor"
country	Conditional	String	Country code.	"MY"
postcode	Yes	Numeric	Postcode.	"46300"

Object: holderImage

Field Name	Required	Type	Description	Example
contentEncoding	Yes	String	Encoding format of the image.	"base64"
contentMediaType	Yes	String	Media type of the image data.	"jpeg"
image	Yes	String	Entire image data.	"/9j/4AAQSkZJRgABAQ"

Object: extractedData (For Passport)

Field Name	Required	Type	Description	Example
issuingStateName	Yes	String	Issuing state name.	"Malaysia"
documentName	Yes	String	Document name.	"Test"
documentType	Yes	String	Document type.	"P"
issuingStateCode	Yes	String	Issuing state code.	"MY"
passportNo	Yes	String	Passport number.	"A123456"
primaryName	Optional	String	Family name.	"Smith"
secondaryName	Optional	String	Given name.	"John"
fullName	Optional	String	Full name.	"John Smith"
nationality	Yes	String	Nationality.	"Malaysia"
dateOfBirth	Yes	String	Date of birth.	"01 MAY 2000"
holderIdNo	Yes	String	Extracted national ID number of the holder.	"1234567890"
gender	Yes	String	Gender.	"M"
placeOfBirth	Yes	String	Place of birth.	"Kuala Lumpur"
dateOfIssue	Yes	String	Date of issue.	"01 NOV 2010"
issuingAuthority	Yes	String	Issuing authority.	"Test"
dateOfExpiry	Yes	String	Date of expiry.	"01 NOV 2015"
holderPortrait	Yes	Object	Image of the holder's face.	Refer to explanation below.
holderMark	Optional	Object	Image of either holder’s thumb print or signature.	Refer to explanation below.

Object: holderPortrait

Field Name	Required	Type	Description	Example
contentEncoding	Yes	String	Encoding format of the image.	"base64"
contentMediaType	Yes	String	Media type of the image data.	"jpeg"
image	Yes	String	Entire image data.	"/9j/4AAQSkZJRgABAQ"

Object: holderMark

Field Name	Required	Type	Description	Example
contentEncoding	Yes	String	Encoding format of the image.	"base64"
contentMediaType	Yes	String	Media type of the image data.	"jpeg"
image	Yes	String	Entire image data.	"/9j/4AAQSkZJRgABAQ"

Object: recommendation

Field Name	Required	Type	Description	Example
result	Yes	String	Result.	"T"
score	Yes	String	Score.	"100"
identificationCheck	Yes	Object	Identification check.	Refer to explanation below.
threshold	Yes	String	Threshold.	"80"

Object: identificationCheck

Field Name	Required	Type	Description	Example
result	Yes	String	Result.	"T"
score	Yes	String	Score.	"20"
threshold	Yes	String	Threshold.	"10"
type	Yes	String	Type.	"Landmark"
maxScore	Yes	String	Maximum score.	"20"

Example Message

Request

/aivpersonidtfy POST Request

curl -X POST "https://xxx.finexusgroup.com/AIV/rest/clientauth/aivpersonidtfy" \
 -H "Accept: application/json" \
 -H "Content-Type: application/json" \ 
 -d '{
          "sourceInfo": {
          "source": "test",
          "partnerId": "test",
          "productType": "appTest",
          "reference": " AIVref220610181940",
          "apiVersion": "1.6",
          "apiKey": "",
          "userId": "",
          "userToken": ""
          },
          "interactionMode": {
          "callbackUrl": "",
          "mode": "SYNC"
          },
          "idType": "mykad",
          "language":"en",
          "fullName": "Wong XXX XXX",
          "nationality": "MY",
          "idNo": "97XXXXXXXXXX",
          "idImage": {
               "imageFront": {
                    "image": "iVBORw0KGgoAAAANSUhEUgAAAtsAAAH",
                    "contentMediaType": "image/jpeg",
                    "contentEncoding": "base64"
               },
               "imageBack": {
                    "image": "iVBORw0KGgoAAAANSUhEUgAAApkAAAG",
                    "contentMediaType": "image/jpeg",
                    "contentEncoding": "base64"
               }
          },
          "device": {
               "imei": "",
               "model": "",
               "brand": "",
               "mac": ""
          }
     }'

Response

/aivpersonidtfy POST Response

{
    "status": {
        "sourceInfo": {
            "reference": "2003160192931",
            "apiVersion": "1.6",
            "apiKey": "ABC1234567",
            "source": "FNXCARDS",
            "partnerId": "BSSS",
            "productType": "Card Application",
            "userId": "mkchan",
            "userToken": "APPOKJSID8J1234"
        },
        "errorList": [
            {
                "msgText": "",
                "msgCode": ""
            }
        ],
        "status": "SUCCESS"
    },
    "payload": {
        "possibleFraud": "t",
        "qualityOfIdImage": "t",
        "idType": "mykad",
        "extractedData": {
            "placeOfBirth": "Kuala Lumpur",
            "myKadNo": "000000000000",
            "address": {
                "addrLine1": "No.1, Jalan Pangkor",
                "addrLine2": "Titiwangsa Sentral",
                "addrLine3": "",
                "city": "Kuala Lumpur",
                "postcode": "50000",
                "state": "W.P. Kuala Lumpur",
                "country": "MY"
            },
            "muslimFlag": "f",
            "gender": "M",
            "holderImage": {
                "image": "/9j/4AAQSkZJRgABAQ",
                "contentMediaType": "jpeg",
                "contentEncoding": "base64"
            },
            "fullName": "John Smith"
        },
        "recommendation": {
            "result": "F",
            "score": 70,
            "identificationCheck": [
                {
                    "result": "T",
                    "score": 25,
                    "threshold": 20,
                    "type": "Landmarks",
                    "maxScore": 25
                },
                {
                    "result": "T",
                    "score": 25,
                    "threshold": 20,
                    "type": "Name",
                    "maxScore": 25
                },
                {
                    "result": "T",
                    "score": 25,
                    "threshold": 20,
                    "type": "MyKadNo",
                    "maxScore": 25
                },
                {
                    "result": "T",
                    "score": 25,
                    "threshold": 20,
                    "type": "address",
                    "maxScore": 25
                }
            ],
            "threshold": 85
        },
        "insufficientLandmarkDetection": "f",
        "landmark": {
            "landmarkDetails": {
                "icPlateMatch": "f",
                "chipLogoMatch": "f",
                "myKadLogoMatch": "f",
                "coatOfArmsMatch": "f",
                "portraitMatch": "f",
                "citizenFlg": "f",
                "TnGLogoMatch": "f",
                "myFlagMatch": "f",
                "ketuaPengarahTextFound": "f"
            },
            "landmarkResult": {
                "authenticityFlg": "F",
                "matchedNo": 0,
                "totalNo": 10,
                "threshold": 4
            }
        },
        "aivRefId": "205"
    }
}