tencent cloud

APIs

DocumentationAPIseKYCFace Identity Verification PaaS APIsCheckIdCardInformation

CheckIdCardInformation

Focus Mode
Font Size
Last updated: 2026-04-24 16:15:48

1. API Description

Domain name for API request: faceid.intl.tencentcloudapi.com.

This API is used to import the ID card portrait side photo, recognize the information on the ID card photo, and compare the name, identity card number, and ID card portrait photo with the ID photo in the authoritative database to verify if they belong to the same person, thereby verifying the authenticity of the identity card information.

A maximum of 100 requests can be initiated per second for this API.

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common Params. The value used for this API: CheckIdCardInformation.
Version Yes String Common Params. The value used for this API: 2018-03-01.
Region No String Common Params. This parameter is not required for this API.
ImageBase64 No String

Base64 value of the ID card portrait side.

  • Supported image formats: PNG, JPG, JPEG. GIF format is not currently supported.
  • Supported image size: the downloaded image should be no more than 7M after Base64 encoding.
  • Please use the standard Base64 encoding method (with = padding). Refer to RFC4648 for coding specification.
  • Either ImageBase64 or ImageUrl must be provided. If both are provided, proceed to use parameters according to the priority of ImageUrl > ImageBase64.
ImageUrl No String

Url address of the ID card portrait side

  • Supported image formats: PNG, JPG, JPEG. GIF format is not currently supported.
  • Supported image size: The downloaded image after Base64 encoding is no more than 3M. Image download time is no more than 3 seconds.
  • Images stored in Tencent Cloud's Url can guarantee higher download speed and stability. It is recommended to store images in Tencent Cloud.
  • Speed and stability of non-Tencent Cloud Storage URLs may be impacted to a certain extent.
Config No String

Configuration.

  • All the following optional fields are bool type, default false.
    CopyWarn, alarm for photocopy.
    BorderCheckWarn, border and frame block alarm.
    ReshootWarn, alarm for rephotographing.
    DetectPsWarn, PS detection alarm (suspected PS traces).
    TempIdWarn, temporary ID card alarm.
    Quality, image Quality alarm (evaluates blurriness).

  • SDK configuration method for reference:
    Config = Json.stringify({"CopyWarn":true,"ReshootWarn":true}).

  • API 3.0 Explorer setting method for reference:
    Config = {"CopyWarn":true,"ReshootWarn":true}.
IsEncrypt No Boolean

Whether required to encrypt sensitive information in the response.

  • Default false.
  • Sensitive information includes Response.IdNum and Response.Name.
IsEncryptResponse No Boolean

Whether required to encrypt the response body.
Encryption No Encryption

Whether required to encrypt sensitive information in the response, need to be specified encryption algorithm Algorithm, initial vector for CBC encryption, and encrypted symmetric key.

3. Output Parameters

Parameter Name Type Description
Sim Float

Similarity. - Value ranges from 0.00 to 100.00. - Recommend threshold at least 70 to judge as same person, self-adjust based on specific scenario (pass rate for threshold 70 is 0.01%).
Result String

Business error code.

  • Success case returns Success.
  • For error conditions, refer to the FailedOperation part in the error code list below.
Description String

Business result description.
Name String

Name.
Sex String

Gender.
Nation String

Ethnicity.
Birth String

Date of birth.
Address String

Address.
IdNum String

Identity card number.
Portrait String

The base64 encoding of the ID card portrait photo. If the image cropping fails, it will compare with the entire ID card and return null.
Warnings String

Alarm information.

  • When alarm information is configured in Config, portrait comparison will be disabled, Result returns an error (FailedOperation.OcrWarningOccurred) with this alarm information.

  • Code list of alarm codes and definition:
    '-9101': Incomplete ID card border alarm.
    '-9102': ID card copy alarm.
    '-9103': ID card photocopy alarm.
    '-9105': ID card frame occlusion alarm.
    '-9104': Temporary ID card alarm.
    '-9106': ID card PS alarm (suspected PS traces).
    '-8001': Warn about blurry images.

  • Multiple codes are separated by "
Quality Float

Image quality score.

  • This parameter is significant only when warn about blurry images is configured in the request Config.
  • Value ranges from 0 to 100. The current default threshold is 50. A score lower than 50 triggers blurry image warnings.
Encryption Encryption

Sensitive data encryption info.


Note: This field may return null, indicating that no valid values can be obtained.
EncryptedBody String

Encrypted data.
RequestId String The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

4. Example

Example1 Verifying an ID Card Portrait Photo Failure Example

Input Example

https://faceid.intl.tencentcloudapi.com/?Action=CheckIdCardInformation
&ImageBase64=/9j/4AAQSkZJRg.....s97n//2Q==
&Config={"CopyWarn":true}
&<Common request parameters>

Output Example

{
    "Response": {
"Address": "No. 4 Jingshan Front Street, Dongcheng District, Beijing, Jing Shi Fang, Forbidden City"
        "Birth": "1654/12/20",
"Description": "OCR alert occurred"
        "IdNum": "11204416541220243X",
"Name": "Wei Xiaobao"
"Nation": "Manchu"
        "Portrait": "/9j/4AAQSk...Se/wDkf//Z",
        "Quality": 99,
        "Encryption": null,
        "RequestId": "6e6cfaad-3271-4eb1-a203-2866100eb283",
        "Result": "FailedOperation.OcrWarningOccurred",
"Sex": "Male",
        "Sim": 0,
        "Warnings": "-9101"
    }
}

Example2 Successful Example of ID Card Portrait Photo Verification

Input Example

https://faceid.intl.tencentcloudapi.com/?Action=CheckIdCardInformation
&ImageBase64=/9j/4AAQSkZJRg.....s97n//2Q==
&Config={"CopyWarn":true}
&<Common request parameters>

Output Example

{
    "Response": {
"Address": "No. 4 Jingshan Front Street, Dongcheng District, Beijing, Jing Shi Fang, Forbidden City"
        "Birth": "1654/12/20",
"Description": "Success"
        "Encryption": null,
        "IdNum": "11204416541220243X",
"Name": "Wei Xiaobao"
"Nation": "Han"
        "Portrait": "/9j/4AAQSk...m3Zt62P//Z",
        "Quality": 98,
        "RequestId": "8dc2b640-caad-4a13-ad8c-204d46d29fe1",
        "Result": "Success",
"Sex": "Male",
        "Sim": 99.76,
        "Warnings": ""
    }
}

5. Developer Resources

SDK

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

Command Line Interface

6. Error Code

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

Error Code Description
FailedOperation.CompareFail Comparison failed.
FailedOperation.CompareLowSimilarity The comparison similarity did not reach the passing standard.
FailedOperation.CompareSystemError Error calling the comparison engine API.
FailedOperation.DownLoadError File download failed.
FailedOperation.EmptyImageError Image content is empty.
FailedOperation.EncryptSystemError Encryption failed.
FailedOperation.FileSaveError Failed to store file. Please retry later.
FailedOperation.IdFormatError Input identity card number error.
FailedOperation.IdNameMisMatch Name and ID card number mismatch. Please verify and try again after.
FailedOperation.IdNoExistSystem The number is not found in the database. Please go to the place of household registration to verify.
FailedOperation.IdPhotoNoExist The photo of this number is not found in the database. Please go to the place of household registration to verify.
FailedOperation.IdPhotoPoorQuality Document image is of poor quality. Please update and try again.
FailedOperation.IdPhotoSystemNoanswer The customer database, self-built database, or authentication center failed to return the photo. Try again later.
FailedOperation.ImageBlur The image is blurry.
FailedOperation.ImageDecodeFailed Image decoding failed.
FailedOperation.ImageNoIdCard No ID card is detected in the image.
FailedOperation.ImageSizeTooLarge The image is too large.
FailedOperation.LifePhotoDetectFaces Multiple faces are detected.
FailedOperation.LifePhotoDetectFake Real person comparison failed.
FailedOperation.LifePhotoDetectNoFaces Failed to detect a full face.
FailedOperation.LifePhotoPoorQuality The resolution of the image passed in is too low. Please upload a new one.
FailedOperation.LifePhotoSizeError The image passed in is too large or too small.
FailedOperation.OcrFailed Ocr recognition failed.
FailedOperation.RequestLimitExceeded The number of calls exceeded the limit.
FailedOperation.StsUnAuthErrError STS unauthorized.
FailedOperation.UnKnown Unknown internal error.
InternalError.EncryptSystemError Encryption failed.
InternalError.UnKnown Unknown internal error.
InvalidParameter Invalid parameter.
UnauthorizedOperation.Arrears The account is in arrears.
UnauthorizedOperation.ChargeStatusException The billing status is abnormal.
UnauthorizedOperation.Nonactivated The service has not been activated.
Previous Topic: ImageRecognitionV2Next Topic: GetFaceIdTokenIntl

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback