DescribeSmartVerify
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
| Parameter | Type | Required | Example | Description |
| SceneId | Long | Yes | 100000**** | 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. |
| CertifyId | String | Yes | 91707dc296d469ad38e4c5efa6a0**** | The certification ID. Call the InitSmartVerify operation to submit an authentication request and obtain this ID. |
Response parameters
| Parameter | Type | Required | Example | Description |
| RequestId | String | Yes | 130A2C10-B9EE-4D84-88E3-5384FF039795 | The request ID. |
| Message | String | No | success | The response message. |
| Code | String | Yes | 200 | The response code. A value of 200 means the request was successful. |
| ResultObject.Passed | String | No | T | Indicates whether the authentication passed. Valid values:
Note This parameter is not returned if an API error occurs or the authentication status is pending. |
| ResultObject.PassedScore | String | No | 80.2 | The 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.SubCode | String | No | 200 | The authentication result code. For more information, see ResultObject.SubCode values. |
| ResultObject.MaterialInfo.ocrIdCardInfo | String | No | {"ocrIdCardInfo": {ID card field information} } | The OCR information of the ID card. |
| ResultObject.MaterialInfo.ocrPictureInfo | String | No | {"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.riskInfo | String | No | {"riskInfo": { "score": 35,"tags": "rm0114"} } | The business security information. For more information, see Additional information about ResultObject.MaterialInfo.riskInfo. |
| ResultObject.MaterialInfo.deviceInfo | String | No | {"deviceInfo": {"tags": "is_rooted","umid": "f98580e024684ea3e2acbe7aa7e1****"}} | The device security information. For more information, see Additional information about ResultObject.MaterialInfo.deviceInfo. |
| ResultObject.MaterialInfo.facePictureInfo | String | No | {"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.verifyInfo | String | No | {"verifyInfo": { "authorityComparisionScore": 26,"idCardFaceComparisonScore": 26} } | The verification information. The structure is as follows:
|
{
// 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
}
}| Error code | Description | Billed | Description |
| 200 | Authentication passed. | Yes | The authentication passed. |
| 201 | Identity verification failed. | Yes | Authentication failed. The user's identity information may not match, be incorrect, or not be found. |
| 202 | Identity information cannot be found. | Yes | Authentication 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. |
| 203 | Photo not found or unavailable. | Yes | Authentication failed. The authoritative comparison source may not have a photo available. |
| 204 | Face comparison with the authoritative source failed. | Yes | Authentication failed. The person in the photo may not be the authorized user, or the liveness detection photo may be of poor quality. |
| 205 | A risk was detected during liveness detection. | Yes | Authentication failed. An attack risk was detected. |
| 206 | Restricted by business policy. | Yes | Authentication failed. The user's action poses a risk. |
| 207 | The face does not match the ID card photo. | Yes | Authentication failed. The face does not match the ID card photo. |
| 208 | Recaptured ID card photo detected. | Yes | Authentication failed. The submitted ID card photo might be a copy, a non-original, or otherwise invalid. |
| 209 | The authoritative comparison source is unavailable. | Yes | Authentication failed. The authoritative comparison source is unavailable for comparison. |
| 210 | Device risk detected. | Yes | Authentication failed. A security risk was detected on the device. |
| 211 | Security policy risk detected. | Yes | Authentication failed. The user's action poses a security risk. |
ResultObject.MaterialInfo.riskInfo
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
scoreand risk levels is as follows.Value range Risk level Suggested action [0,35) Low risk Allow. [35,65) Medium risk Flag for observation. [65,85) Medium-high risk Perform further security verification or restrict permissions. [85,100) High risk Restrict permissions. - For financial security scenarios, the mapping between the
scoreand risk levels is as follows.Value range Risk level Suggested action [0,35) Low risk Allow. [35,70) Medium risk Flag for observation. [70,100) High risk Restrict permissions.
- For marketing security and account security scenarios, the mapping between the
- The following table describes the
tags(risk tags).Scenario type (Mode) Value Description Marketing security (MARKET_SAFE) and Account security (ACCOUNT_SAFE) rm0101, rm0102, rm0103, rm0111, rm0112, rm0113, rm0114 risky_mobile: Risk related to the mobile phone number. rn0301, rn0302, rn0303, rn0311, rn0312, rn0313, rn0315 risky_net: Network risk. rd0401, rd0402, rd0411, rd0412 risky_device: Device risk. ra0601, ra0602, ra0603 risky_activities: User activity risk. Financial security (FINANCE_SAFE) md000, md010, md020, md030 risky_finance: Financial risk.
| Scenario type | Value | Description |
| All business scenario types | is_emulator | The device may be an emulator. Supported on Android and iOS. |
| is_rooted | The device may be rooted. Supported only on Android. | |
| is_virtual | The device may be running in a multi-instance environment. Supported only on Android. | |
| is_tampered | The device information may be tampered with. Supported only on Android. | |
| is_deviceCluster_h | The device may be a high-risk device in a device farm. Supported only on Android. | |
| is_deviceCluster_m | The device may be a medium-risk device in a device farm. Supported only on Android. | |
| no_tag | No risk features were found. |
Examples
See Java SDK example.
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
| Code | Message | Description |
| 200 | success | The request was successful. |
| 400 | Parameter can not be empty | A required parameter is empty. |
| 406 | Invalid certifyId | The specified CertifyId is invalid. |
| 410 | Service is not activated | The OSS service is inactive, or you have not granted read/write permissions for OSS. For more information, see Authorize Smart Verify to access OSS. |
| 411 | RAM permission denied | The RAM user does not have the required permissions. You must grant the AliyunYundunCloudAuthFullAccess policy to the RAM user. |
| 424 | Identity authentication record does not exist | No authentication record is associated with the specified CertifyId. |
| 500 | System error | An internal system error occurred. |