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
- Response
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 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
- Response
/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" \
/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"
}
}
}