All Products
Search

This Product

    ID Verification:Server-side API operation

    Document Center

    ID Verification:Server-side API operation

    Last Updated:Sep 17, 2026

    This topic describes how to configure the server side for FACE_GUARD_PRO.

    API information

    • API operation: FaceGuardRisk

    • Request method: POST and GET

    • Protocol: HTTPS

    • Important

      FACE_GUARD_PRO is billed per successful query. We recommend that you do not repeatedly query the same Device Token after a successful query to avoid duplicate billing.

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

    • Global endpoints:

      Note

      • 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.

      • To meet data collection compliance requirements in different regions, Device Helper provides separate data reporting sites. Data is isolated between these sites.

        The client specifies the reporting site by setting CustomUrl and CustomHost. Your server must then access the endpoint corresponding to the reported site to retrieve detailed information.

      Asia Pacific SE 1 (Singapore)

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

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

      Asia Pacific SE 5 (Jakarta)

      • 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

      US West 1 (Silicon Valley)

      • Public endpoint: cloudauth-intl.us-west-1.aliyuncs.com

      • Internal endpoint: cloudauth-intl-vpc.us-west-1.aliyuncs.com

      Europe Central 1 (Frankfurt)

      • Public endpoint: cloudauth-intl.eu-central-1.aliyuncs.com

      • Internal endpoint: cloudauth-intl-vpc.eu-central-1.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 run this API in OpenAPI Explorer to debug it and generate an SDK sample code.

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    ProductCode

    String

    Yes

    The product code. Set this to FACE_GUARD_PRO.

    FACE_GUARD_PRO

    MerchantBizId

    String

    Yes

    A unique business identifier that you define for troubleshooting. The value can be a combination of letters and digits up to 32 characters in length. Make sure that the identifier is unique.

    e0c34a77f5ac40a5aa5e6ed2********

    DeviceToken

    String

    Yes

    The deviceToken obtained from the client SDK.

    Tk9SSUQuMS*****************ZDNmNWY5NzQxOW1o

    BizId

    String

    No

    The unique ID of the current business authentication, used together with FACE_GUARD_PRO for verification during queries.

    1000******0001

    Response parameters

    Name

    Type

    Description

    Example

    RequestId

    String

    The request ID.

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

    Code

    String

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

    Success

    Message

    String

    This section provides detailed descriptions of the return codes.

    success

    Result.TransactionId

    String

    The unique identifier of the entire authentication process.

    e0c34a77f5ac40a5aa5e6ed2********

    Result.RiskTags

    String

    The risk tags of the device. Separate multiple tags with a comma ,. For more information about device risk tags and their meanings, see Device Guard risk tags.

    ROOT,VPN,HOOK

    Result.RiskExtends

    String

    For more information, see Result.RiskExtends.

    {
  "code": "Success",
  "message":"success",
  "umid":"07d3295d3d597b425d102a7f********",
  "sip":"198.51.100.1",
  "durationMs" : 4968931,
  "queryCount":1,
  "querySessionCount":1,
  "queryUmidCount":1,
  "platform":"Android"
}

    Result.GuardRiskScore

    Double

    The device risk likelihood predicted by the device assistant algorithm. A higher score indicates a higher device risk.

    Valid values: 0 to 100.

    99

    Result.RiskExtends

    Field

    Meaning

    Detailed description

    code

    Token status code

    • 200: The token is normal.

    • 401: The data in the token is abnormal.

    • 404: The data format in the token is abnormal.

    • 407: The token has expired (valid for 7 days).

    • 408: The token or reported data has been tampered with.

    • 500: An unknown token exception occurred.

    message

    Token error message

    The token error message. This field is populated when the code is not 200.

    umid

    Unique device ID

    07d3295d3d597b425d102a7f********

    platform

    Device platform

    • Android

    • iOS

    • Harmony

    • Web

    sip

    Client IP address

    198.51.100.1

    durationMs

    The elapsed time between client-side initialization and the query, in milliseconds.

    4968931

    queryCount

    The number of times the token was used for queries on the current day.

    1

    querySessionCount

    The number of times the session associated with the token was used for queries on the current day.

    2

    queryUmidCount

    The number of times the device was used for queries on the current day.

    2