Retrieve Results of the Person's Information

/aivpersonidtfy

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

info

This method will retrieve the result for a specific /aivpersonidtfy POST request submitted previously.

• For a synchronous interaction mode ( mode is “SYNC” ), this method can be used to get the result of the prior submitted POST request, if the request had been terminated prematurely before the return of a response;
• For an asynchronous interaction mode ( mode is “ASYNC” ), this method can be used to get the result of the earlier submitted POST request after waiting a specific interval.

Request

Request Parameters

Field Name	Required	Type	Length	Description	Example
source	Yes	String	16	Source.	"FNXCRDS"
partnerId	Yes	String	128	Partner ID.	"BSSS"
productType	Optional	String	128	Product type.	"appTest"
reference	Yes	String	64	Reference.	"ID00000213132"
apiKey	Conditional	String	64	Api key.	"1233214HSC"
apiVersion	Yes	String	8	Api version.	"1.6"
referenceId	Yes	String	64	Reference ID.	"272391d1cc5840b2abfb7340a317e353f9eswc4nyQ0CEqw"
language	Optional	String	2	Language.	"en","ms"

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.	AIVPersonIdtfyGetResponse
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	Length	Description	Example
status	Yes	Object		Status.	Refer to explanation below.
payload	Optional	Object		Result of the authenticity of ID document.	Refer to explanation below.

Object: status

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

Object: sourceInfo

Field Name	Required	Type	Length	Description	Example
source	Yes	String	16	Source.	"FNXCRDS"
partnerId	Yes	String	128	Partner ID.	"BSSS"
productType	Optional	String	128	Partner type.	"appTest"
reference	Yes	String	64	Reference.	"ID00000213132"
apiVersion	Yes	String	8	API version.	"1.6"
apiKey	Conditional	String	64	API key.	"1233214HSC"
userId	Optional	String	32	User ID.	"mkchan"
userToken	Optional	String	64	User token.	"APPOKJSID8J1234"

Object: errorList

Field Name	Required	Type	Length	Description	Example
msgCode	Yes	String	8	Message code.
msgText	Yes	String	128	Message text.

Object: payload

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

Object: status

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

Object: sourceInfo

Field Name	Required	Type	Length	Description	Example
source	Yes	String	16	Source.	"FNXCRDS"
partnerId	Yes	String	128	Partner ID.	"BSSS"
productType	Optional	String	128	Partner type.	"appTest"
reference	Yes	String	64	Reference.	"ID00000213132"
apiVersion	Yes	String	8	API version.	"1.6"
apiKey	Conditional	String	64	API key.	"1233214HSC"
userId	Optional	String	32	User ID.	"mkchan"
userToken	Optional	String	64	User token.	"APPOKJSID8J1234"

Object: errorList

Field Name	Required	Type	Length	Description	Example
msgCode	Yes	String	8	Message code.
msgText	Yes	String	128	Message text.

Object: payload

Field Name	Required	Type	Length	Description	Example
landmark	Yes	Object		Landmark.	Refer to explanation below.
aivRefId	Yes	String	64	AIV reference ID.	"272391d1cc5840b2abfb7340a317e353f9eswc4nyQ0CEqw"
idType	Optional	String	32	ID type.	"MYKAD", "PASSPORT"
extractedData	Optional	Object		Extracted data.	Refer to explanation below.
possibleFraud	Yes	String	1	Possible fraud.	"t","f"
qualityOfIdImage	Yes	String	1	Quality of ID image.	"t","f"
insufficientLandmarkDetection	Yes	String	1	Insufficient landmark detection.	"t","f"
recommendation	Yes	Object		Recommendation.	Refer to explanation below.

Object: landmark

Field Name	Required	Type	Length	Description	Example
landmarkResult	Yes	Object		Landmark result.	Refer to explanation below.
landmarkDetails	Yes	Object		Landmark details.	Refer to explanation below.

Object: landmarkResult

Field Name	Required	Type	Length	Description	Example
totalNo	Yes	String (Numeric)	4	Total number of landmarks defined.	"10"
matchedNo	Yes	String (Numeric)	4	Number of matched landmarks.	"0"
threshold	Yes	String (Numeric)	4	Number of matched thresholds.	"4"
authenticityFlg	Yes	String	1	Authenticity flag.	"F","T"

Object: landmarkDetails (For MyKad)

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

Object: landmarkDetails (For Passport)

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

Object: extractedData (For MyKad)

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

Object: address

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

Object: holderImage

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

Object: extractedData (For Passport)

Field Name	Required	Type	Length	Description	Example
issuingStateName	Yes	String	256	Issuing state name.	"Malaysia"
documentName	Yes	String	64	Document name.	"Test"
documentType	Yes	String	1	Document type.	"P"
issuingStateCode	Yes	String	2	Issuing state code.	"MY"
passportNo	Yes	String	16	Passport number.	"A123456"
primaryName	Optional	String	128	Primary name.	"Smith"
secondaryName	Optional	String	128	Secondary name.	"John"
fullName	Optional	String	128	Full name.	"John Smith"
nationality	Yes	String	64	Nationality.	"Malaysia"
dateOfBirth	Yes	String	256	Date of birth.	"01 MAY 2000"
holderIdNo	Yes	String	20	National ID number of the holder.	"1234567890"
gender	Yes	String	1	Gender.	"M","F"
placeOfBirth	Yes	String	256	Place of birth.	"Kuala Lumpur"
dateOfIssue	Yes	String	16	Date of issue.	"01 NOV 2010"
issuingAuthority	Yes	String	64	Issuing authority.	"Test"
dateOfExpiry	Yes	String	16	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	Length	Description	Example
contentEncoding	Yes	String	16	Encoding format of the image.	"BASE64"
contentMediaType	Yes	String	16	Media type of the image data.	"jpeg"
image	Yes	String		Entire image data.	"/9j/4AAQSkZJRgABAQ"

Object: holderMark

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

Object: recommendation

Field Name	Required	Type	Length	Description	Example
result	Yes	String	1	Result.	"T","F"
score	Yes	String (Numeric)	4	Score.	"100"
identificationCheck	Yes	Object		Identification check.	Refer to explanation below.
threshold	Yes	String (Numeric)	4	Threshold.	"80"

Object: identificationCheck

Field Name	Required	Type	Length	Description	Example
result	Yes	String	1	Result.	"T","F"
score	Yes	String (Numeric)	4	Score.	"20"
threshold	Yes	String (Numeric)	4	Threshold.	"10"
type	Yes	String	128	Type.	"Landmark"
maxScore	Yes	String (Numeric)	4	Maximum score.	"20"

Example Message

Request

/aivpersonidtfy GET Request

curl -X GET "https://xxx.finexusgroup.com/AIV/rest/clientauth/aivpersonidtfy?source=FNXCRDS&partnerId=BSSS&productType=appTest&reference=ID00000213132&apiVersion=1.6&referenceId=272391d1cc5840b2abfb7340a317e353f9eswc4nyQ0CEqw&apiKey=1233214HSC" \
 -H "Accept: application/json" \
 -H "Content-Type: application/json" \ 

Response

/aivpersonidtfy GET Response

{
   "status": {
      "sourceInfo": {
           "reference": "ID00000213132",
           "apiVersion": "1.6",
           "apiKey": "1233214HSC",
           "source": "FNXCARDS",
           "partnerId": "BSSS",
           "productType": "appTest",
        "referenceId": "272391d1cc5840b2abfb7340a317e353f9eswc4nyQ0CEqw",
        "language": "en"
      },
      "errorList": [
           {
              "msgText": "",
              "msgCode": ""
           }
      ],
      "status": "SUCCESS"
   },
   "payload": {
      "status": {
           "sourceInfo": {
              "reference": "ID00000213132",
              "apiVersion": "1.6",
              "apiKey": "1233214HSC",
              "source": "FNXCARDS",
              "partnerId": "BSSS",
              "productType": "appTest",
             "userId": "",
             "userToken": ""
           },
           "errorList": [
              {
                "msgText": "",
                "msgCode": ""
              }
           ],
           "status": "SUCCESS"
      },
      "payload": {
           "possibleFraud": "t", 
           "qualityOfIdImage": "t",
           "idType": "mykad",
           "extractedData": {
                "placeOfBirth": "",
                "myKadNo": "",
                "address": {
                    "country": "",
                    "addrLine3": "bl",
                    "city": "",
                    "addrLine2": ".. Jw",
                    "addrLine1": "JALAN",
                    "postcode": "",
                    "state": ""
                },
                "muslimFlag": "f",
                "gender": "",
                "holderImage": {
                    "image": "/9j/4AAQSkZJRgABAQ"
                    "contentMediaType": "jpeg",
                    "contentEncoding": "base64"
                },
                "fullName": ""
           },
   "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": "",
           "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"
      }
   }
}