All Products
Search

This Product

    ID Verification:CheckResult

    Document Center

    ID Verification:CheckResult

    Last Updated:Oct 23, 2026

    This topic describes how to query authentication results using the CheckResult API operation.

    API information

    • API operation: CheckResult

    • Request method: HTTPS POST

    • Description: When the server-side receives a callback indicating that authentication is complete, call this API to retrieve the corresponding authentication status and information. This callback is sent when the client result code is 1001 or 1002. For more information, see Native SDK client result codes and sub-codes.

      Important

      The ID Verification service stores verification results for 30 days by default. Please retrieve them within this period, as they are automatically deleted afterward.

    • QPS limit: Each API has its own QPS limit. For more information, see QPS limits of ID Verification server-side APIs.

    • Service endpoint:

      Note

      • Benefits of internal network access: An internal network is a private communication network connecting Alibaba Cloud products within the same region. If your application server is deployed in the same region, use the internal endpoint to access the ID Verification service for enhanced security and stability.

      • Optimizing overseas access: Overseas network environments can be complex. Refer to Optimize server network latency to tune your integration and reduce network latency and request failures.

      Asia Pacific SE 1 (Singapore)

      • Public endpoint: cloudauth-intl.ap-southeast-1.aliyuncs.com

      • Internal endpoint: cloudauth-intl-vpc.ap-southeast-1.aliyuncs.com

      Indonesia

      • Public endpoint: cloudauth-intl.ap-southeast-5.aliyuncs.com

      • Internal endpoint: cloudauth-intl-vpc.ap-southeast-5.aliyuncs.com

      China (Hong Kong)

      • Public endpoint: cloudauth-intl.cn-hongkong.aliyuncs.com

      • Internal endpoint: cloudauth-intl-vpc.cn-hongkong.aliyuncs.com

      Asia Pacific SE 3 (Kuala Lumpur)

      • Public endpoint: cloudauth-intl.ap-southeast-3.aliyuncs.com

      • Internal endpoint: cloudauth-intl-vpc.ap-southeast-3.aliyuncs.com

    Online debugging and integration

    Note

    Before debugging and integration, read the Use OpenAPI document to learn how to call APIs on the OpenAPI platform and obtain the SDK.

    You can test this API operation directly in OpenAPI Explorer, and generate SDK sample code.

    Integration notes

    1. TransactionId storage: The TransactionId is a trusted server-side identifier for an authentication record. It must be bound to your business ID and stored persistently on the App Server.

    2. Log retention period: Authentication result logs are stored for 30 days by default and then automatically deleted. You must query the results within this period and save the required data in compliance with relevant regulations.

    3. Video acquisition and retention compliance: A video is returned only when the corresponding feature is enabled and the authentication is successful. The download URL for the evidence video is valid for 15 minutes. The original video is automatically deleted 30 minutes after the authentication is complete. If your business needs to retain the video, download it promptly and strictly comply with local privacy and data compliance requirements.

    4. Image acquisition: An authentication image is returned only when IsReturnImage is set to Y and the face liveness verification is successful. Because Base64-encoded data is large, keep this parameter set to its default value of N if you do not need to display or retain the image.

    5. API status vs. authentication result: A Code value of Success indicates only that the API operation was called successfully. The final authentication result depends on the Result.Passed and Result.SubCode fields.

    6. Troubleshooting authentication failures: If Passed is N, analyze the SubCode and ExtFaceInfo fields to determine the cause of the failure.

    Field distribution

    Both App SDK and Web SDK integrations use the same CheckResult API operation and query parameters. The main authentication result structure is consistent. The main differences are the extension fields of ExtFaceInfo and the fallback information for mobile H5.

    Category

    Field

    Description

    Shared outputs

    Common response, authentication result

    Returned in both integration modes. Whether it is returned depends on the authentication flow and the InitializeV2 configuration.

    Web SDK specific

    faceQuality, faceOcclusion, faceAge, faceGender, ExtInfo.procedurePriority

    Face quality, occlusion, age, gender, and the actual fallback policy on the web client.

    App specific

    None

    None

    Request parameters

    Field

    Type

    Required

    Description

    Example

    MerchantBizId

    String

    Yes

    A unique business ID from the merchant, consisting of 32 letters and numbers. It must be consistent with the value used in the InitializeV2 request.

    e0c34a77f5ac40a5aa5e6ed20c35****

    TransactionId

    String

    Yes

    The unique authentication identifier returned by a successful init API call. To prevent tampering, always retrieve this value from your server-side storage and do not trust the value sent from the client-side.

    hksb7ba1b28130d24e015d6********

    IsReturnImage

    String

    No

    Specifies whether to return authentication images. If the package includes a certificate, the certificate image is also returned.

    • Y: Return

    • N: Do not return (default)

    Y

    Response data

    Name

    Type

    Description

    Example

    HTTP Status Code

    Integer

    The HTTP status code.

    200

    HTTP Body

    RequestId

    String

    The request ID, which is used for troubleshooting.

    130A2C10-B9EE-4D84-88E3-5384FF03****

    Code

    String

    The server-side return code. For more information, see Server-side HTTP status codes.

    Success

    Message

    String

    A detailed description of the return code.

    success

    Result.Passed

    String

    The final authentication result. Valid values:

    • Y: The authentication is passed.

    • N: The authentication is not passed.

    Y

    Result.SubCode

    String

    A description of the authentication result. For more information, see Result.SubCode authentication result sub-codes.

    200

    Result.ExtFaceInfo

    String

    The results of face liveness verification. For more information, see Result.ExtFaceInfo.

    {
  "faceAttack": "N",
  "faceImg": "/9j/4AAQSkZJRgABAQAAAQqviV6oakp8...",
  "docVideoUrl": "https://aliyun-cloudauth.oss-aliyuncs.com/******.webm" 
}

    Result.ExtInfo

    String

    Other authentication information, which mainly includes the actual fallback information for mobile H5. For more information, see Result.ExtInfo.

    {
  "procedurePriority": "keep"
}

    Result.ExtFaceInfo

    Name

    Type

    Description

    Example

    faceImg

    String

    The live face image in Base64 format. Returned only when IsReturnImage=Y and the face scan is successful.

    Base64 format

    docVideoUrl

    String

    The OSS download URL for the evidence video. This may be returned only when the DocVideo parameter in InitializeV2 is set to Y and the video is successfully uploaded. The URL is valid for 15 minutes. You can query it repeatedly within 30 minutes after the authentication is complete. After 30 minutes, the video is deleted and cannot be recovered.

    https://aliyun-cloudauth.oss-aliyuncs.com/******.webm

    faceAttack

    String

    Indicates whether a liveness attack was detected:

    • Y: Yes

    • N: No

    N

    faceAttackScore

    (Deprecated)

    Double

    The liveness attack risk score, ranging from 0 to 100.

    The risk of liveness attacks is now determined by a Large Language Model (LLM), so the concept of a risk score is no longer applicable. This field is offline.

    80

    guardRiskScore

    Double

    The device risk score, ranging from 0 to 100. A higher score indicates a higher device risk.

    90

    deviceToken

    String

    The DeviceToken for Face Guard. It is returned when the Face Guard module is fully integrated and can be used to query the Face Guard server-side API operations to get device risk details.

    • Face Guard is a paid service. For more information, see Billing overview.

    • This token is valid for 7 days and is not unique.

    e0c34a77f5ac40a5aa5e6ed20c35****

    faceAttributeInfo

    String

    Detects the facial attributes of the main face in an input image. The main face is the one that is largest, clearest, and closest to the camera. The detection results are returned as a string. You can use this string to make decisions about the content.

    The returned fields are defined as follows:

    • gender: The gender of the main entity. A value of 1 indicates male, and 0 indicates female.

    • glasses: Indicates whether the main entity is wearing glasses. A value of 1 indicates that glasses are detected, and 0 indicates that they are not.

    • hat: Indicates whether the main entity is wearing a hat. This includes headscarves or veils. A value of 1 indicates that a hat is detected, and 0 indicates that it is not.

    • mask: Indicates whether the main entity is wearing a mask. A value of 1 indicates that a mask is detected, and 0 indicates that it is not.

    • tattoo: Indicates whether the main entity has a visible tattoo. A value of 1 indicates that a tattoo is detected, and 0 indicates that it is not.

    • smoking: Indicates whether the main entity is smoking. A value of 1 indicates that smoking is detected, and 0 indicates that it is not.

    • others: Indicates whether people other than the main entity are present. A value of 1 indicates that other people are detected, and 0 indicates that they are not.

    • env: The environment of the main entity, such as an office, factory, hospital, or vehicle. The system currently supports returning office, hospital, factory, vehicle, or other.

    • expression: Indicates whether the main entity has an exaggerated expression. An exaggerated expression is a strong facial expression that is distinct from a natural or calm state. A value of 1 indicates that an exaggerated expression is detected, and 0 indicates that it is not.

    • age: The age of the main entity in years.

    {
        gender: 1,
        glasses: 0,
        hat: 1,
        mask: 1,
        tattoo: 0,
        smoking: 0,
        others: 1,
        env: "office",
        expression: 1,
        age: 16
}

    Result.ExtInfo

    Field

    Type

    Description

    procedurePriority

    String

    The actual downgrade method for mobile H5 authentication:

    • keep: No downgrade

    • url: Downgrade using a URL

    Result.SubCode authentication result sub-codes

    Error code

    Billing for authentication records

    Description and suggestions

    200

    Yes

    The authentication is passed.

    205

    Yes

    [Liveness Attack] A risk was detected during liveness detection.

    206

    Yes

    [Liveness Attack] Limited by business policy. After safe mode is enabled, the device and environment are checked for security. If a potential risk is detected, the authentication fails.

    You can troubleshoot and handle this as follows:

    1. Remind the user to uninstall any multi-instance, cloning, or virtual environment software or plugins from the device, and then retry after restoring the device's initial security environment.

    2. Check if the package name used is a test demo package name. If so, change it to the business package name to avoid being blocked by the project's or service's security policy.