DescribeSmartVerify

Updated at:

Queries the result of a Smart Verify process.

API name: DescribeSmartVerify.

service address: cloudauth.aliyuncs.com.

request method: POST and GET.

transfer protocol: HTTPS.

After the mobile client receives a callback, your server calls this operation to get the authentication status and data.

Request parameters

ParameterTypeRequiredExampleDescription
SceneIdLongYes100000****

The scene ID.

You must create an authentication scenario in the Smart Verify console to obtain a scene ID. For more information, see Add an authentication scenario.

CertifyIdStringYes91707dc296d469ad38e4c5efa6a0****The certification ID.

Call the InitSmartVerify operation to submit an authentication request and obtain this ID.

Response parameters

ParameterTypeRequiredExampleDescription
RequestIdStringYes130A2C10-B9EE-4D84-88E3-5384FF039795The request ID.
MessageStringNosuccessThe response message.
CodeStringYes200The response code. A value of 200 means the request was successful.
ResultObject.PassedStringNoTIndicates whether the authentication passed. Valid values:
  • T: Passed.
  • F: Failed.
Note This parameter is not returned if an API error occurs or the authentication status is pending.
ResultObject.PassedScoreStringNo80.2The overall decision score, ranging from 0 to 100.

A score of 80 or higher indicates the authentication passed, while a score below 80 indicates it failed.

ResultObject.SubCodeStringNo200The authentication result code. For more information, see ResultObject.SubCode values.
ResultObject.MaterialInfo.ocrIdCardInfoStringNo{"ocrIdCardInfo": {ID card field information} }The OCR information of the ID card.
ResultObject.MaterialInfo.ocrPictureInfoStringNo{"ocrPictureInfo":{"ossBucketName":"cn-shanghai-aliyun-cloudauth-1260051251634779","ossIdFaceObjectName":"smart/126005125*****/efcda7614d1f0a5f41dbc914xxxx_ocridface_6756.jpeg","ossIdNationalEmblemObjectName":"smart/126005125xxxx/efcda7614d1f0a5f41dbc9xxxxx_ocridnationalemblem_5277.jpeg","ossIdFaceUrl":"https://cn-shanghai-aliyun-cloudauth-xxxxxx.oss-cn-shanghai.aliyuncs.com/smart/xxxxx/xxxxx.jpeg","ossIdNationalEmblemUrl":"https://cn-shanghai-aliyun-cloudauth-xxxxxx.oss-cn-shanghai.aliyuncs.com/smart/xxxxx/xxxxx.jpeg"}}The ID card photos.
Note The returned links are valid for 15 minutes.
ResultObject.MaterialInfo.riskInfoStringNo{"riskInfo": { "score": 35,"tags": "rm0114"} }The business security information. For more information, see Additional information about ResultObject.MaterialInfo.riskInfo.
ResultObject.MaterialInfo.deviceInfoStringNo{"deviceInfo": {"tags": "is_rooted","umid": "f98580e024684ea3e2acbe7aa7e1****"}}The device security information. For more information, see Additional information about ResultObject.MaterialInfo.deviceInfo.
ResultObject.MaterialInfo.facePictureInfoStringNo{"facePictureInfo":{"ossBucketName":"cn-shanghai-aliyun-cloudauth-126005125xxxx","ossFaceObjectName":"smart/126005125xxxx/adc6048e5355deecabff8374b6xxxx_face_ed03.jpeg","pictureUrl":"https://cn-shanghai-aliyun-cloudauth-xxxxxx.oss-cn-shanghai.aliyuncs.com/smart/xxxxx/xxxxx.jpeg"}}The face photo.
Note The returned links are valid for 15 minutes.
ResultObject.MaterialInfo.verifyInfoStringNo{"verifyInfo": { "authorityComparisionScore": 26,"idCardFaceComparisonScore": 26} }The verification information. The structure is as follows:
  • authorityComparisionScore: String. The comparison score between the submitted face photo and the photo from the authoritative comparison source. The value ranges from 0 to 100.
    Confidence threshold reference:
    • A threshold of 95 corresponds to a 0.001% false acceptance rate.
    • A threshold of 90 corresponds to a 0.01% false acceptance rate.
    • A threshold of 80 corresponds to a 0.1% false acceptance rate.
    • A threshold of 60 corresponds to a 1% false acceptance rate.
  • idCardFaceComparisonScore: String. The comparison score between the submitted face photo and the face on the ID card's portrait side. The value ranges from 0 to 100.
    Confidence threshold reference:
    • A threshold of 95 corresponds to a 0.001% false acceptance rate.
    • A threshold of 90 corresponds to a 0.01% false acceptance rate.
    • A threshold of 80 corresponds to a 0.1% false acceptance rate.
    • A threshold of 60 corresponds to a 1% false acceptance rate.
Example of ResultObject.MaterialInfo in JSON format:
{
    // ID card information. This parameter is returned only when Ocr=T.
    "ocrIdCardInfo": {
        // Field information of the ID card.
    },
    // OSS storage information for the ID card photos. This parameter is returned only when Ocr=T.
    "ocrPictureInfo": {
        // The name of the bucket that stores the OCR photos of the ID card.
        "ossBucketName": "cn-shanghai-aliyun-cloudauth-1260051251634779",
        // The file name of the portrait side of the OCR-scanned ID card.
        "ossIdFaceObjectName": "smart/126005125xxxxx/efcda7614d1f0a5f41dbc914xxxx_ocridface_6756.jpeg",
        // The file name of the national emblem side of the OCR-scanned ID card.
        "ossIdNationalEmblemObjectName": "smart/126005125xxxx/efcda7614d1f0a5f41dbc9xxxxx_ocridnationalemblem_5277.jpeg",
        // The URL of the portrait side photo of the ID card.
        "ossIdFaceUrl":"https://cn-shanghai-aliyun-cloudauth-xxxxxx.oss-cn-shanghai.aliyuncs.com/smart/xxxxx/xxxxx.jpeg",
        // The URL of the national emblem side photo of the ID card.
        "ossIdNationalEmblemUrl":"https://cn-shanghai-aliyun-cloudauth-xxxxxx.oss-cn-shanghai.aliyuncs.com/smart/xxxxx/xxxxx.jpeg"
    },
    // Business security information.
    "riskInfo": {
         // The score.
         "score": 35,
         // The tag.
         "tags": "rm0114"
    },
    // Device security information.
    "deviceInfo": {
   // The device security tag.
    "tags": "is_rooted",
 // The unique device ID.    
    "umid": "f98580e024684ea3e2acbe7aa7e116aa"
    },
    // Information about the face photo stored in OSS.
    "facePictureInfo": {
        // The name of the bucket that stores the face photo.
        "ossBucketName": "cn-shanghai-aliyun-cloudauth-126005125xxxx",
        // The file name of the face photo.
        "ossFaceObjectName": "smart/126005125xxxx/adc6048e5355deecabff8374b6xxxx_face_ed03.jpeg",
        // The URL of the face photo.
        "pictureUrl":"https://cn-shanghai-aliyun-cloudauth-xxxxxx.oss-cn-shanghai.aliyuncs.com/smart/xxxxx/xxxxx.jpeg"
},
    // Authentication result information.
    "verifyInfo": {
        // The comparison score between the submitted face photo and the photo from the authoritative data source.
        "authorityComparisionScore": 26,
        // The comparison score between the submitted face photo and the face on the ID card's portrait side.
        "idCardFaceComparisonScore": 26
    }
}
ResultObject.SubCode values
Error codeDescriptionBilledDescription
200Authentication passed.YesThe authentication passed.
201Identity verification failed.YesAuthentication failed. The user's identity information may not match, be incorrect, or not be found.
202Identity information cannot be found.YesAuthentication failed. This can occur if the user has a special status, such as recent household registration changes or military service. Consider providing a manual review option.
203Photo not found or unavailable.YesAuthentication failed. The authoritative comparison source may not have a photo available.
204Face comparison with the authoritative source failed.YesAuthentication failed. The person in the photo may not be the authorized user, or the liveness detection photo may be of poor quality.
205A risk was detected during liveness detection.YesAuthentication failed. An attack risk was detected.
206Restricted by business policy.YesAuthentication failed. The user's action poses a risk.
207The face does not match the ID card photo.YesAuthentication failed. The face does not match the ID card photo.
208Recaptured ID card photo detected.YesAuthentication failed. The submitted ID card photo might be a copy, a non-original, or otherwise invalid.
209The authoritative comparison source is unavailable.YesAuthentication failed. The authoritative comparison source is unavailable for comparison.
210Device risk detected.YesAuthentication failed. A security risk was detected on the device.
211Security policy risk detected.YesAuthentication failed. The user's action poses a security risk.

ResultObject.MaterialInfo.riskInfo

The ResultObject.MaterialInfo.riskInfo parameter includes a score (risk score) and tags (risk tags). Details are as follows:
  • The score (risk score) ranges from 0 to 100. A higher value indicates a higher risk level.
    • For marketing security and account security scenarios, the mapping between the score and risk levels is as follows.
      Value rangeRisk levelSuggested action
      [0,35)Low riskAllow.
      [35,65)Medium riskFlag for observation.
      [65,85)Medium-high riskPerform further security verification or restrict permissions.
      [85,100)High riskRestrict permissions.
    • For financial security scenarios, the mapping between the score and risk levels is as follows.
      Value rangeRisk levelSuggested action
      [0,35)Low riskAllow.
      [35,70)Medium riskFlag for observation.
      [70,100)High riskRestrict permissions.
  • The following table describes the tags (risk tags).
    Scenario type (Mode)ValueDescription
    Marketing security (MARKET_SAFE) and Account security (ACCOUNT_SAFE)rm0101, rm0102, rm0103, rm0111, rm0112, rm0113, rm0114risky_mobile: Risk related to the mobile phone number.
    rn0301, rn0302, rn0303, rn0311, rn0312, rn0313, rn0315risky_net: Network risk.
    rd0401, rd0402, rd0411, rd0412risky_device: Device risk.
    ra0601, ra0602, ra0603risky_activities: User activity risk.
    Financial security (FINANCE_SAFE)md000, md010, md020, md030risky_finance: Financial risk.
ResultObject.MaterialInfo.deviceInfo
Scenario typeValueDescription
All business scenario typesis_emulatorThe device may be an emulator. Supported on Android and iOS.
is_rootedThe device may be rooted. Supported only on Android.
is_virtualThe device may be running in a multi-instance environment. Supported only on Android.
is_tamperedThe device information may be tampered with. Supported only on Android.
is_deviceCluster_hThe device may be a high-risk device in a device farm. Supported only on Android.
is_deviceCluster_mThe device may be a medium-risk device in a device farm. Supported only on Android.
no_tagNo risk features were found.

Examples

See Java SDK example.

Note

To get SDK code samples in other languages, use OpenAPI Explorer to debug the API online. OpenAPI Explorer automatically generates samples after a successful call.

Error codes

CodeMessageDescription
200successThe request was successful.
400Parameter can not be emptyA required parameter is empty.
406Invalid certifyIdThe specified CertifyId is invalid.
410Service is not activatedThe OSS service is inactive, or you have not granted read/write permissions for OSS. For more information, see Authorize Smart Verify to access OSS.
411RAM permission deniedThe RAM user does not have the required permissions. You must grant the AliyunYundunCloudAuthFullAccess policy to the RAM user.
424Identity authentication record does not existNo authentication record is associated with the specified CertifyId.
500System errorAn internal system error occurred.