All Products
Search

This Product

    ID Verification:ID_OCR_MIN.

    Document Center

    ID Verification:ID_OCR_MIN.

    Last Updated:Jun 25, 2026

    Integrate the DocOcrV2 API to extract information from ID document images and detect spoofing threats on the server side.

    API information

    • API operation name: DocOcrV2

    • Request method: HTTPS POST

    • Description: Extracts information from ID documents (passports, ID cards, etc.) and performs anti-spoofing checks using OCR.

    • QPS limit: Each API has a dedicated QPS limit. For details, see QPS limits of ID Verification server-side APIs.

    • Endpoint:

      Note

      • Benefits of internal network access: An internal network enables private communication between Alibaba Cloud services in the same region. If your application server is also in the same region, use the internal network endpoint to access the ID Verification service for a more secure and stable connection. 

      • Optimization for overseas access: Network conditions outside the Chinese mainland can be complex. To reduce latency and minimize request failures, optimize your integration by following the best practices in Server-side Network Latency Analysis and Optimization.

      China (Hong Kong)

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

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

    Online debugging and integration

    Note

    Before you debug or integrate, read the Debug and integrate server-side APIs with OpenAPI guide to understand how to call APIs on the OpenAPI platform and how to obtain the SDK.

    You can debug this API operation in OpenAPI Explorer and generate SDK sample code for it.

    Image format requirements

    To ensure stable model performance, make sure that the uploaded images meet all the following requirements:

    • Supported image formats: JPG, JPEG, and PNG.

    • Image size: The recommended size is 50 KB to 100 KB. The maximum size is 1 MB.

      Note

      Converting an image to base64 format typically increases the data size. If you pass the image as a base64-encoded string, ensure the original image size does not exceed 6 MB to stay within the 10 MB data transfer limit.

    • Image resolution: Image dimensions must be between 200 and 8,192 pixels. The recommended resolution is 480 × 640 (height × width).

    • Image quality recommendations:

      • Ensure that all four corners of the card image are visible. Avoid obstructing any part of the card, as this can affect detection.

      • Ensure the card image is clear, properly oriented, and free of obstructions or glare.

      • The card should occupy more than 60% of the total image area. If the card area is too small, recognition may be affected.

      • Use photos of the actual physical document.

    Request parameters

    Name

    Type

    Required

    Description

    Example

    ProductCode

    String

    Yes

    The product plan. Set to ID_OCR_MIN for the ID document OCR API.

    ID_OCR_MIN

    SceneCode

    String

    No

    A custom authentication scenario ID for querying related records in the console. Maximum 10 characters; supports letters, digits, and underscores (_).

    1234567890

    MerchantBizId

    String

    Yes

    A unique business ID for tracking and troubleshooting. Maximum 32 characters; supports letters and digits.

    Note

    Alibaba Cloud does not enforce uniqueness. Ensure this value is unique for effective tracking.

    e0c34a77f5ac40a5aa5e6ed20c35****

    MerchantUserId

    String

    Yes

    A user identifier such as a phone number or email address. We recommend hashing this value before submission.

    123456789

    IdOcrPictureBase64

    String

    No

    Note

    You can choose any one of the three upload methods.

    The base64-encoded image of the portrait side of the ID document. Ensure the image does not exceed the size limit.

    base64

    IdOcrPictureUrl

    String

    The publicly accessible HTTP or HTTPS URL of the portrait side of the ID document.

    https://***

    IdOcrPictureFile

    InputStream

    ID document image file stream.

    For specific integration methods, see File uploads with the Advance interface.

    DocType

    String

    Yes

    The ID document type, an 8-digit identifier. See List of document types.

    F

    Ocr

    String

    Yes

    Whether to enable OCR for automatic document information extraction.

    • T: Enable the OCR feature.

    • F: Disable the OCR feature.

    T

    IdFaceQuality

    String

    No

    Whether to return the face quality score on the ID document. Disabled by default.

    Note

    This parameter is valid only for the portrait side of the ID document.

    • T: Return the face quality score.

    • F: Do not return the face quality score.

    F

    Spoof

    String

    No

    Whether to enable anti-spoofing detection for the ID document. Disabled by default.

    Note

    This parameter is valid only for the portrait side of the ID document.

    • T: Enable the anti-spoofing feature.

    • F: Disable the anti-spoofing feature.

    F

    IdThreshold

    String

    No

    Sets the mode for the OCR quality check. Valid values are:

    • 0: standard mode

    • 1: strict mode

    • 2: loose mode

    • 3 (default): Disables the quality check.

    3

    CardSide

    String

    No

    The side of the ID document to recognize. Defaults to the portrait side.

    • OCR_ID_FACE (Default): Portrait side

    • OCR_ID_NATIONAL_EMBLEM: National emblem side

    Important

    This parameter applies only to resident identity cards of the People's Republic of China.

    OCR_ID_NATIONAL_EMBLEM

    List of document types

    DocType

    Corresponding document

    01000000

    Global passport

    00000006

    Hong Kong identity card (2003 edition)

    00000008

    Hong Kong identity card (2018 edition)

    00000007

    Exit-Entry Permit for Travelling to and from Hong Kong and Macao

    00000009

    Mainland Travel Permits for Hong Kong and Macao Residents

    000000011

    Macao identity card

    000000012

    Mainland Travel Permit for Taiwan Residents

    00000001

    Second-generation resident identity card of the Chinese mainland

    Response parameters

    Name

    Type

    Description

    Example

    HTTP Status Code

    Integer

    The HTTP status code.

    200

    HTTP Body

    RequestId

    String

    The request ID.

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

    Result.TransactionId

    String

    The unique ID for the entire authentication process.

    hksb7ba1b28130d24e015d694361b****

    Code

    String

    Return code: For more information, see Server-side HTTP status codes.

    Success

    Message

    String

    A detailed description of the response code.

    success

    Result.Passed

    String

    The authentication result. Valid values:

    • Y: Passed

    • N: Failed

    Y

    Result.SubCode

    String

    The authentication result description. For more information, see ResultObject.SubCode error codes.

    200

    Result.ExtIdInfo

    String

    The ID document recognition result in JSON format. See the example on the right and ExtIdInfo.

    {
  "idFaceQualityScore": 98.0,
  "ocrIdInfo": {
    "expiryDate": "",
    "originOfIssue": "Bureau of Exit and Entry Administration of the Ministry of Public Security",
    "englishName": "LI SI",
    "sex": "Male",
    "name": "Li Si",
    "idNumber": "H11111112",
    "issueDate": "2013-01-02",
    "birthDate": "1990-02-21"
  },
  "spoofInfo": {
    "spoofResult": "Y",
    "spoofType": [
      "SCREEN_REMARK"
    ]
  }
}

    ExtIdInfo

    Name

    Type

    Description

    Example

    ocrIdInfo

    String

    The OCR fields of the ID document. See OCR recognition response fields.

    Note

    If the ID document OCR process fails, this field is empty. 

    {
  "expiryDate": "",
  "originOfIssue": "Bureau of Exit and Entry Administration of the Ministry of Public Security",
  "englishName": "LI SI",
  "sex": "Male",
  "name": "Li Si",
  "idNumber": "H11111112",
  "issueDate": "2013-01-02",
  "birthDate": "1990-02-21"
}

    idFaceQualityScore

    Double

    The face quality score in the ID document image. Range: 0–100.

    99.95

    spoofInfo

    String

    The result of spoof detection, including the risk decision and risk types:

    Note

    Card spoofing detection is enabled only when IdSpoof = Y in the Initialize request.

    Otherwise, spoofResult defaults to N, and spoofType is empty.

    • spoofResult:

      • Y: Risk detected

      • N: Normal

    • spoofType:

      • SCREEN_REMARK: screen recapture

      • PHOTO_COPY: photocopy

      • TAMPER: tampering

      • SHORTCUT: screenshot

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

    ResultObject.SubCode error codes

    Note

    Subcode is returned based on different product solutions or integration methods. For details, refer to the following table.

    Applicable solution

    Error code

    Is authentication record billed

    Description and suggested reasons

    General

    200

    Yes

    Authentication passed.

    • ID_OCR pure server-side integration (DocOcr)

    • ID_OCR_MAX

    211

    Yes

    The quality or resolution of the certificate image does not meet requirements, or the image itself is incomplete. Ensure the photo of the certificate's portrait side is clear, has normal exposure, is complete without occlusion, and has no significant angle deviation.

    • ID_OCR App (SDK) integration

    • ID_OCR Web (SDK) integration

    • ID_OCR_MAX

    212

    Yes

    Certificate anti-counterfeiting detection indicates risk. There may be high-risk operations such as rephotographing, tampering, or photocopying.

    • ID_OCR pure server-side integration (DocOcr)

    • ID_OCR_MAX

    213

    Yes

    The specified certificate type was not detected (recognition mode) or the certificate type could not be identified (classification mode).

    We recommend uploading a clear, complete certificate image with normal angle.

    OCR response fields

    Hong Kong permanent identity card

    Note

    Both the 2003 and 2018 versions of the Smart Identity Card are supported.

    Parameter

    Type

    Description

    name

    String

    Name

    englishName

    String

    Name (English)

    nameCode

    String

    Chinese commercial code

    sex

    String

    Sex. Valid values:

    • M: Male

    • F: Female

    birthDate

    String

    Date of birth

    idNumber

    String

    ID card number

    currentIssueDate

    String

    Date of registration

    firstIssueDate

    String

    Month and year of first registration

    isPermanent

    String

    Specifies whether this is a permanent identity card. Valid values:

    • Y: Yes

    • N: No

    symbols

    String

    Symbol code. For example: "***AZ".

    Exit-entry permit for Hong Kong and Macao

    Parameter

    Type

    Description

    name

    String

    Name

    englishName

    String

    Name (Pinyin)

    sex

    String

    Sex

    birthDate

    String

    Date of birth

    idNumber

    String

    Document number

    issueDate

    String

    Date of issue

    expiryDate

    String

    Expiry date

    placeOfIssue

    String

    Place of issue

    originOfIssue

    String

    Issuing authority

    Mainland permit for Hong Kong and Macao residents

    Parameter

    Type

    Description

    name

    String

    Name

    englishName

    String

    Name (English)

    sex

    String

    Sex

    birthDate

    String

    Date of birth

    idNumber

    String

    Document number

    issueDate

    String

    Date of issue

    expiryDate

    String

    Expiry date

    originOfIssue

    String

    Issuing authority

    Mainland permit for Taiwan residents

    Parameter

    Type

    Description

    name

    String

    Name

    englishName

    String

    Name (Pinyin)

    sex

    String

    Sex

    birthDate

    String

    Date of birth

    idNumber

    String

    Document number

    issueDate

    String

    Date of issue

    expiryDate

    String

    Expiry date

    originOfIssue

    String

    Issuing authority

    placeOfIssue

    String

    Place of issue

    e-passport

    Note

    This document type reads the Machine-Readable Zone (MRZ) of ICAO-compliant e-Passports. Extracting a standard set of fields ensures compatibility across passports from different countries, which often have varying formats.

    Parameter

    Type

    Description

    surname

    String

    Surname in Latin script from the MRZ.

    givenname

    String

    Given name in Latin script from the MRZ.

    sex

    String

    Sex, returned as F or M.

    birthDate

    String

    Date of birth, in yyyy-mm-dd format.

    passportNo

    String

    Passport number

    nationality

    String

    Nationality, represented by a 3-letter country code.

    expiryDate

    String

    Expiry date, in yyyy-mm-dd format.

    countryCode

    String

    Country code of the issuing authority.

    (3-letter country code)

    Macao resident identity card

    Parameter

    Type

    Description

    surnameCN

    String

    Surname (Chinese)

    givennameCN

    String

    Given name (Chinese)

    surname

    String

    Surname (English)

    givenname

    String

    Given name (English)

    sex

    String

    Sex

    birthDate

    String

    Date of birth

    idNumber

    String

    Document number

    expiryDate

    String

    Expiry date

    placeOfBirth

    String

    Code for the place of birth. For example: "***AZ".

    Chinese mainland ID card

    Parameter

    Type

    Description

    name

    String

    Name

    sex

    String

    Sex

    ethnicity

    String

    Ethnicity

    birthDate

    String

    Date of birth

    idNumber

    String

    ID number

    address

    String

    Address

    province

    String

    Province

    Note

    Reserved field. Returns empty by default.

    city

    String

    City

    Note

    Reserved field. Returns empty by default.

    originOfIssue

    String

    Issuing authority

    issueDate

    String

    Date of issue

    expiryDate

    String

    Expiry date