ID Verification:CheckResult

API description

• Operation name: 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.

• Endpoints:

  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

  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

  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

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

Integration notes

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

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

3. Video acquisition and retention compliance: Videos are returned only when the corresponding feature is enabled and the authentication process is successful. The download link for an 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 videos, download them promptly and strictly comply with local privacy and data compliance requirements.

4. Image acquisition specifications: Authentication images are returned only when IsReturnImage is set to Y and the face verification is successful. Because Base64 data is large, you can keep this parameter at its default value N if you do not need to display or retain the images.

5. Distinguishing between API status and authentication result: A value of Success for the Code parameter only indicates that the API call was successful. The final authentication result must be based on the Result.Passed and Result.SubCode fields.

6. Troubleshooting authentication failures: If Passed is N, you must determine the cause of the failure by checking the SubCode, ExtFaceInfo, ExtIdInfo, and ExtSourceInfo (if it exists) fields.

7. Field parsing compatibility: The returned content, such as Optical Character Recognition (OCR) fields, the number of certificate pages, and facial attributes, varies dynamically based on the certificate type, regional service capabilities, and SDK configuration. Your client-side parsing logic must be backward-compatible to ensure normal operation when fields are missing or added.

Field distribution description

The main response structure, liveness detection results, and OCR result fields of CheckResult are consistent for both App SDK and Web SDK integrations.

Request parameters (common)

Return Data

{
  "faceAttack": "N",
  "faceComparisonScore": 99.99,
  "faceImg": "base64 format",
  "facePassed": "Y",
  "faceQuality": 95.45,
  "faceOcclusion": "N",
  "docVideoUrl": "https://aliyun-cloudauth.oss-aliyuncs.com/******.webm" 
}

{
  "ocrIdInfoData": {
    "01": {
      "ocrIdInfo": {
        "id_number": "083099003767",
        "full_name": "MAC PHAM HOÀNG DƯƠNG",
        "nationality": "Vietnam",
        "date_of_expiry": "",
        "date_of_birth": "16/08/1999",
        "sex": "Male"
      },
      "ocrIdPassed": "Y",
      "spoofInfo": {
        "spoofResult": "N"
      }
    },
    "02": {
      "ocrIdInfo": {
        "date_of_issue": "10/02/2022",
        "personal_identification": "Dot-shaped scar approx. 2 cm above and behind the right corner of the mouth."
      },
      "ocrIdPassed": "Y",
      "spoofInfo": {
        "spoofResult": "N"
      }
    }
  },
  "ocrIdPassed": "Y"
}

{
  "govId": 1.0,
  "fullName": 1.0,
  "dob": 0.9,
  "selfiePhoto": 0.8777,
  "liveness": 0.1152,
  "imgManipulationScore": 0.2253
}

{
  "procedurePriority": "keep"
}

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

{
  "01": 
    "ocrIdInfo": {
      "expiryDate": "2030.01.01",
      "englishName": "SUN, xxx",
      "originOfIssue": "National Immigration Administration",
      "placeOfIssue": "Beijing",
      "sex": "Male",
      "name": "Sun X",
      "idNumber": "CGxxxxxxxx",
      "issueDate": "2024.12.01",
      "birthDate": "1992.12.01"
    },
    "ocrIdPassed": "Y",
    "spoofInfo": {
      "spoofResult": "N"
    }
  }
}

{
  "expiryDate": "2026-01-02",
  "originOfIssue": "Exit and Entry Administration of the Ministry of Public Security",
  "englishName": "ZHANG SAN",
  "sex": "Male",
  "name": "Zhang San",
  "idNumber": "H11111115",
  "issueDate": "2013-01-02",
  "birthDate": "1990-02-21"
}

{
    "given_name_s": "HYUNEUI",
    "surname_s": "MUN",
    "date_of_expiry_s": "2028-02-08",
    "date_of_birth_s": "1988-10-26",
    "sex_s": "M"
}

{
  "expiryDate": "2030.01.01",
  "englishName": "SUN, xxx",
  "originOfIssue": "National Immigration Administration",
  "placeOfIssue": "Beijing",
  "sex": "Male",
  "name": "Sun X",
  "idNumber": "CGxxxxxxxx",
  "issueDate": "2024.12.01",
  "birthDate": "1992.12.01"
}

{
 "spoofResult": "Y",
 "spoofType": ["SCREEN_REMARK"]
}

Result.ExtSourceInfo

Field descriptions for the Indonesian data source:

Result.ExtInfo

Result.SubCode authentication result subcode descriptions

FAQ

faceComparisonScore: What is the false acceptance rate (FAR) for the face comparison threshold, and what are the corresponding thresholds for different FARs?

The false acceptance rate (FAR) is the probability that the system incorrectly identifies a non-matching person as a matching person. A lower FAR value indicates higher security. The thresholds that correspond to each FAR value are as follows: