tencent cloud

APIs

DocumentationAPIseKYCReal-name Information Verification APIsIdCardOCRVerification

IdCardOCRVerification

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

1. API Description

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

This API is used to validate the authenticity and consistency of the name and identity card number. You can provide the required verification information by manually inputting the name and identity card number or importing the ID card portrait side image.

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: IdCardOCRVerification.
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.
IdCard No String Identity card number.
-Name, identity card number, ImageBase64, or ImageUrl must provide one of the three.
-If both are provided, proceed to use parameters according to the priority of name and identity card number > ImageBase64 > ImageUrl.
Name No String Name
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 after Base64 encoding is no more than 3M. Please use the standard Base64 encoding method (with = padding). Refer to RFC4648 for the coding specification.
ImageUrl No String Url of the ID card portrait side.
-Supported image formats: PNG, JPG, JPEG. GIF format is not currently supported.
-Supported image size: The downloaded image is no more than 3M after Base64 encoding. Image download time is no more than 3 seconds.
-Images stored on Tencent Cloud's Url guarantee higher download speed and stability. It is advisable to store images on Tencent Cloud.
-The speed and stability of non-Tencent Cloud Storage URLs may be impacted.
Encryption No Encryption Sensitive data encryption info.
-Users with encryption requirements for incoming information (name, identity card number) can use this parameter. For details, please click the left-side link.

3. Output Parameters

Parameter Name Type Description
Result String Verification result code. Billing is as follows.
-Result code for charges
The name and identity card number match.
-Name and ID card number mismatch.
-Result code with no charge
-2: Invalid ID number (incorrect length or check digit).
-3: Invalid name (incorrect length or format).
-4: Document library service exception.
-5: No ID card record found in the document library.
-6: The authoritative comparison system is being upgraded. Try again later.
-7: Authentication attempts exceeded the daily limit.
Description String Business result description.
Name String Name to verify.
IdCard String Identity card number to verify.
Sex String Gender obtained by OCR.
Note: This field may return null, indicating that no valid values can be obtained.
Nation String Ethnicity obtained by OCR.
Note: This field may return null, indicating that no valid values can be obtained.
Birth String Birthday obtained by OCR.
Note: This field may return null, indicating that no valid values can be obtained.
Address String Address obtained by OCR.
Note: This field may return null, indicating that no valid values can be obtained.
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 with Photo URL Example

Input Example

POST / HTTP/1.1
Host: faceid.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: IdCardOCRVerification
<Common request parameters>

{
    "ImageUrl": "https://www.qq.com/image.jpg"
}

Output Example

{
    "Response": {
        "Result": "0",
"Description": "Name and identity card number match"
"Name": "Wei Xiaobao"
        "IdCard": "11204416541220243X",
"Sex": "Male",
"Nation": "Han"
        "Birth": "1654/12/20",
"Address": "No. 4 Jingshan Front Street, Dongcheng District, Beijing, Jing Shi Fang, Forbidden City"
        "RequestId": "a62f567c-1eea-4ef3-b51a-a9eb9bd84cd9"
    }
}

Example2 Verification Example Using Base64 Image

Input Example

POST / HTTP/1.1
Host: faceid.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: IdCardOCRVerification
<Common request parameters>

{
    "ImageBase64": "/9j/4AAQSkZJRg.....s97n//2Q=="
}

Output Example

{
    "Response": {
        "Result": "0",
"Description": "Name and identity card number match"
"Name": "Wei Xiaobao"
        "IdCard": "11204416541220243X",
"Sex": "Male",
"Nation": "Han"
        "Birth": "1654/12/20",
"Address": "No. 4 Jingshan Front Street, Dongcheng District, Beijing, Jing Shi Fang, Forbidden City"
        "RequestId": "022ffdd2-67a2-4177-8946-97bc1c4b3347"
    }
}

Example3 Verifying with Name and Identity Card Number Example

Input Example

POST / HTTP/1.1
Host: faceid.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: IdCardOCRVerification
<Common request parameters>

{
    "IdCard": "11204416541220243X",
    "Name": "Wei Xiaobao"
}

Output Example

{
    "Response": {
        "Result": "0",
"Description": "Name and identity card number match"
"Name": "Wei Xiaobao"
        "IdCard": "11204416541220243X",
        "Sex": "",
        "Nation": "",
        "Birth": "",
        "Address": "",
        "RequestId": "945c69ad-d86c-47ea-ba33-419b1dc4d242"
    }
}

Example4 Verifying an ID Card and Information Verification Failure Example

Input Example

POST / HTTP/1.1
Host: faceid.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: IdCardOCRVerification
<Common request parameters>

{
    "IdCard": "11204416541220243Y",
    "Name": "Wei Xiaobao"
}

Output Example

{
    "Response": {
        "Address": "",
        "Birth": "",
"Description": "Invalid ID number (incorrect length, check digit, etc.)"
        "IdCard": "11204416541220243Y",
"Name": "Wei Xiaobao"
        "Nation": "",
        "RequestId": "c528602c-6574-4dd7-a836-895ff62a13ed",
        "Result": "-2",
        "Sex": ""
    }
}

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
AuthFailure.InvalidAuthorization CAM signature/authentication error.
FailedOperation.DecryptSystemError Decryption failed.
FailedOperation.DownLoadError File download failed.
FailedOperation.EmptyImageError Image content is empty.
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.OcrFailed Ocr recognition failed.
FailedOperation.StsUnAuthErrError STS unauthorized.
FailedOperation.UnKnown Unknown internal error.
InvalidParameter Invalid parameter.
InvalidParameter.UnsupportEncryptField Unencrypted fields exist. Refer to the documentation to modify.
InvalidParameterValue Incorrect parameter value.
UnauthorizedOperation.Arrears The account is in arrears.
UnauthorizedOperation.ChargeStatusException The billing status is abnormal.
UnauthorizedOperation.NonAuthorize Identity verification has not been completed for the account.
UnauthorizedOperation.Nonactivated The service has not been activated.
Previous Topic: IdCardVerificationNext Topic: CheckIdNameDate

Help and Support

Was this page helpful?

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

Feedback