调用DescribeVerifyResult查询实人认证结果。

接入准备:接入该API时,请确保已经完成相应的准备工作,具体请参见实人认证方案接入流程概述活体人脸验证方案(活体检测方案)接入流程概述

说明 阿里云实人认证仅存储最近180天的认证数据,后续业务上要使用的认证数据,请您及时调用该接口获取并自行转存,以免影响使用。

请求方法:HTTPS POST和GET。

接口描述:当接入方移动端收到回调之后,其服务端可以调用此接口,来获取相应的认证状态和认证资料。

适用范围:该接口适用于无线SDK接入的认证方案。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称 类型 是否必选 示例值 描述
Action String DescribeVerifyResult

要执行的操作。取值:DescribeVerifyResult

BizId String 39ecf51e-2f81-4dc5-90ee-ff86125b****

认证ID。标识一次认证任务的唯一ID,不超过64个字符。针对一次认证任务,系统支持无限次发起提交,直到最终认证通过,该任务完结。

说明 您发起不同的认证任务时需要更换不同的BizId。
BizType String FVBioOnlyTest

实人认证服务的业务场景标识。

返回数据

名称 类型 示例值 描述
AuthorityComparisionScore Float 97

认证过程中所提交的人脸照片和权威数据的比对分,取值范围:0~100

置信度阈值参考:

  • 误识率为0.001%时,对应阈值为95。
  • 误识率为0.01%时,对应阈值为90。
  • 误识率为0.1%时,对应阈值为80。
  • 误识率为1%时,对应阈值为60。
说明 该字段只表示人脸与权威数据的比对结果,仅供您参考,通常不建议业务上仅以该值作为认证是否通过的标准。认证的综合结果请参考VerifyStatus字段。VerifyStatus的结果综合了人脸与权威数据的比对和其他多种策略,可以提高安全水平。
FaceComparisonScore Float 97

认证过程中所提交的人脸照片和人脸留底图片上人脸的比对分,取值范围:0~100

置信度阈值参考:

  • 误识率为0.001%时,对应阈值为95。
  • 误识率为0.01%时,对应阈值为90。
  • 误识率为0.1%时,对应阈值为80。
  • 误识率为1%时,对应阈值为60。
IdCardFaceComparisonScore Float 97

认证过程中所提交的人脸照片和身份证人脸面图片上人脸的比对分,取值范围:0~100

置信度阈值参考:

  • 误识率为0.001%时,对应阈值为95。
  • 误识率为0.01%时,对应阈值为90。
  • 误识率为0.1%时,对应阈值为80。
  • 误识率为1%时,对应阈值为60。
Material Struct

认证材料。

FaceGlobalUrl String http://image-demo.img-cn-hangzhou.aliyuncs.com/face-global-example.jpg

实人认证SDK采集到的摄像头全局图。

说明 该参数需要配置后才会生效。
FaceImageUrl String http://image-demo.img-cn-hangzhou.aliyuncs.com/face-image-example.jpg

人脸正面照图片的HTTP或HTTPS链接。链接地址5分钟内有效,建议您进行转存以免影响使用。

说明 如果人脸正面照图片的HTTP或HTTPS链接过期,可重新调用DescribeVerifyResult获取链接。
FaceMask Boolean false

人脸是否佩戴口罩。取值:

  • true:佩戴了口罩
  • false:未佩戴口罩
FaceQuality String NORMAL

人脸正面照图片的质量。取值:

  • UNQUALIFIED:照片质量较差
  • LOW:低
  • NORMAL:一般
  • HIGH:高
IdCardInfo Struct

身份证信息的OCR结果。

说明 认证过程中如果没有身份证正面和反面信息,实人认证服务则不会返回身份证的OCR结果。认证过程中如果有身份证正面和反面信息,实人认证服务也不一定保证会返回身份证上所有的信息,因身份证拍摄问题引起的OCR无法识别时,OCR信息就会不全,建议您的接入方业务上不强依赖身份证OCR信息。
Address String 浙江省杭州市余杭区文一西路969号

地址。

Authority String 杭州市公安局

签发机构。

BackImageUrl String http://image-demo.img-cn-hangzhou.aliyuncs.com/example3.jpg

身份证国徽面图片的HTTP/HTTPS链接。链接地址5分钟内有效,建议业务上进行转存以免影响使用。

说明 如果人像正面照图片的HTTP/HTTPS链接过期,可重新调用DescribeVerifyResult获取链接。
Birth String 19900101

出生日期。

EndDate String 20201101

证件有效期结束时间。格式为:yyyymmdd。

FrontImageUrl String http://image-demo.img-cn-hangzhou.aliyuncs.com/example2.jpg

身份证人像面图片的HTTP/HTTPS链接。链接地址5分钟内有效,建议业务上进行转存以免影响使用。

说明 如果人像正面照图片的HTTP/HTTPS链接过期,可重新调用DescribeVerifyResult获取链接。
Name String 张三

姓名。

Nationality String

民族。

Number String 02343218901123****

身份证号。

StartDate String 20201101

证件有效期开始时间。格式为:yyyymmdd。

IdCardName String 张三

姓名。

IdCardNumber String 02343218901123****

身份证号。

VideoUrls List -

历史RPH5BioOnly方案返回的录制视频的URL地址。

RequestId String 04F0F334-1335-436C-A1D7-6C044FE73368

本次请求的ID。

VerifyStatus Integer 1

认证状态,取值:

  • -1:未认证
  • 1:认证通过
  • 2~n:各种不同原因导致的认证不通过。详细描述参见认证状态说明。
认证状态说明

VerifyStatus

原因说明

建议处理方法

备注

-1

未认证。可能原因:客户端上的认证请求没有提交成功。例如用户中途主动退出认证流程,或者用户的姓名、身份证号实名校验不匹配等。

重新发起认证。

无。

1

认证通过。

无。

该认证状态在实人认证方案和活体人脸验证方案均会出现。

2

认证不通过,可能原因:实名校验不通过。

核实用户认证的姓名和身份证信息是否有误,重新发起。

该认证状态仅在实人认证方案中出现。

3

认证不通过,可能原因:身份证照片模糊、光线问题造成字体无法识别;身份证照片信息与需认证的身份证姓名不一致;提交的照片为非身份证照片。

使用真实有效证件,在光线充足的场景重新操作。避免证件有遮挡、反光等异常影响认证。

该认证状态仅在实人认证方案中出现。

4

认证不通过,可能原因:身份证照片模糊、光线问题造成字体无法识别;身份证照片信息与需认证的身份证号码不一致、提交的照片为非身份证照片。

使用真实有效证件,在光线充足的场景重新操作。避免证件有遮挡、反光等异常影响认证。

该认证状态仅在实人认证方案中出现。

5

认证不通过,可能原因:身份证照片有效期已过期(或即将过期)或因为识别错误返回过期。

若因为有效期识别错误,可重新发起;若证件已经过期,更换有效期内证件再认证。

该认证状态仅在实人认证方案中出现。

6

认证不通过,可能原因:人脸与身份证头像不一致。

建议用户使用近期的证件重新发起认证,或人工确认无误后通过控制台提交白名单设置后再发起认证。

该认证状态仅在实人认证方案中出现。

7

认证不通过,可能原因:人脸与公安网照片不一致。

人工确认无误后通过控制台提交白名单设置后再发起认证。

该认证状态仅在实人认证方案中出现。

8

认证不通过,可能原因:提交的身份证照片非身份证原照片或未提交有效的身份证照片。

请拍摄真实身份证,不支持手机或电脑存储的证件图片。

该认证状态仅在实人认证方案中出现。

9

认证不通过,可能原因:非账户本人操作;活体检测过程中人脸存在疑似翻拍、遮挡等异常情况;认证发起的设备存在root、hook等风险情况。

建议用户使用正常设备,参考页面提示操作认证,避免面部遮挡、大面积反光。若是测试场景或已经人工确认无误,可通过控制台提交白名单设置后再发起认证。

该认证状态在实人认证方案和活体人脸验证方案均会出现。

10

认证不通过,可能原因:非同一个人操作。

建议更新传入留底的图片,保持正脸完整无遮挡。

该认证状态仅在活体人脸验证方案中出现。

11

认证不通过,可能原因:公安网照片缺失、公安网照片格式错误、公安网照片未找到人脸。

建议用户联系户籍所在地公安局更新信息,若已经人工确认无误,可通过控制台提交白名单设置后再发起认证。

该认证状态仅在实人认证方案中出现。

12

认证不通过,可能原因:公安网系统异常、无法进行照片比对。

建议更换时间重新提交认证,若多次认证均为同一个原因,建议人工核实信息后,可通过控制台提交白名单设置后再发起认证。

该认证状态仅在实人认证方案中出现。

示例

请求示例

https://cloudauth.aliyuncs.com/?Action=DescribeVerifyResult
&RegionId=cn-hangzhou
&BizType=FVBioOnlyTest
&BizId=39ecf51e-2f81-4dc5-90ee-ff86125b****
&<公共请求参数>

正常返回示例

XML格式

<DescribeVerifyResultResponse>
      <Data>
        <VerifyStatus>1</VerifyStatus>
            <Material>
                  <FaceImageUrl>http://image-demo.img-cn-hangzhou.aliyuncs.com/face-image-example.jpg
            </FaceImageUrl>
                  <FaceMask>false</FaceMask>
                  <FaceQuality>HIGH</FaceQuality>
                  <IdCardName>张三</IdCardName>
                  <IdCardNumber>02343218901123****</IdCardNumber>
                  <IdCardInfo>
                        <FrontImageUrl>http://image-demo.img-cn-hangzhou.aliyuncs.com/example2.jpg
                </FrontImageUrl>
                        <BackImageUrl>http://image-demo.img-cn-hangzhou.aliyuncs.com/example3.jpg
                </BackImageUrl>
                        <Name>张三</Name>
                        <Number>02343218901123****</Number>
                        <Birth>19900101</Birth>
                        <Address>浙江省杭州市余杭区文一西路969号</Address>
                        <StartDate>20101101</StartDate>
                        <EndDate>20201101</EndDate>
                        <Authority>杭州市公安局</Authority>
                  </IdCardInfo>
            </Material>
            <AuthorityComparisonScore>97</AuthorityComparisonScore>
      </Data>
</DescribeVerifyResultResponse>

JSON格式

{
    "VerifyStatus": "1",
    "Material": {
        "FaceImageUrl": "http://image-demo.img-cn-hangzhou.aliyuncs.com/face-image-example.jpg",
        "FaceMask": "false",
        "FaceQuality": "HIGH",
        "IdCardName": "张三",
        "IdCardNumber": "02343218901123****",
        "IdCardInfo": {
            "FrontImageUrl": "http://image-demo.img-cn-hangzhou.aliyuncs.com/example2.jpg",
            "BackImageUrl": "http://image-demo.img-cn-hangzhou.aliyuncs.com/example3.jpg",
            "Name": "张三",
            "Number": "02343218901123****",
            "Birth": "19900101",
            "Address": "浙江省杭州市余杭区文一西路969号",
            "StartDate": "20101101",
            "EndDate": "20201101",
            "Authority": "杭州市公安局"
        }
    },
    "AuthorityComparisonScore": "97"
}

错误码

HttpCode 错误码 错误信息 描述
410 DataExpired The data has expired and the records have been deleted. 数据过期,已删除记录(根据合规要求,数据默认存储180天,过期数据将删除,可自行在控制台设置保存期限)。

访问错误中心查看更多错误码。