Help Center> Optical Character Recognition> API Reference> APIs> ID Document
Updated on 2023-04-23 GMT+08:00
View PDF

ID Document

Function

This API identifies and extracts text from images of identity documents issued by multiple countries and regions, such as ID cards, driving licenses, and passports, and converts the text into a structured format. Table 1 lists the mapping between the countries/regions and identity documents. For details about the constraints on using this API, see Constraints. For details about how to use this API, see Introduction to OCR.

Table 1 Mapping between countries/regions and identity documents

Country/Region

Code

Document Type

Vietnam

VNM

PP, DL, and ID

India

IND

PP

Philippines

PHL

PP, DL, ID (UMID only)

Albania

ALB

PP, DL, and ID

Brazil

BRA

PP

Indonesia

IDN

PP

Malaysia

MYS

PP

Nigeria

NGA

PP

Pakistan

PAK

PP

Russia

RUS

PP (Only the international standard version is supported.)

Taiwan (China)

TWN

PP

Ukraine

UKR

PP

Thailand

THA

ID and PP

Chile

CHL

ID and PP

Hong Kong (China)

HKG

ID
  • PP: passport
  • DL: driving license
  • ID: identification card, which is an identity card issued by a country or region, such as an ID card, voter registration card, and social security card.

Constraints

  • Only images in JPEG, JPG, PNG, BMP, or TIFF format can be recognized.
  • No side of the image can be smaller than 15 or larger than 8,192 pixels.

Prerequisites

Before using this API, you need to subscribe to the service and complete authentication. For details, see Subscribing to an OCR Service and Authentication.

Before you use the service for the first time, subscribe to the service by clicking Subscribe. You only need to subscribe to the service once. If you have not subscribed to the service yet, error "ModelArts.4204" will be displayed when you call this API. Before you call the API, log in to the OCR console and subscribe to the corresponding service. Ensure that you make the subscription to the service in the same region where you want to call this API.

Debugging

You can debug this API through automatic authentication in API Explorer. API Explorer can automatically generate and debug sample SDK code.

API Explorer can be called in ap-southeast-1.

URI

POST https://{endpoint}/v2/{project_id}/ocr/id-document

Table 2 URI parameters

Parameter

Mandatory

Description

endpoint

Yes

Endpoint, which is the request address for calling an API.

The endpoint varies depending on services in different regions. For more details, see Endpoints.

project_id

Yes

Project ID, which can be obtained from Obtaining a Project ID.

Request Parameters

Table 3 Request header parameter

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

User token

Used to obtain the permission to call APIs. The token is the value of X-Subject-Token in the response header in Authentication.

Content-Type

Yes

String

MIME type of the request body. The value is application/json.

Enterprise-Project-Id

No

String

Enterprise project ID. OCR uses Enterprise Project Management Service (EPS) to split fees for resources used by different user groups and users.

To obtain the enterprise project ID, go to the Enterprise Project Management page, click the enterprise project name, and obtain the enterprise project ID on the enterprise project details page.

For details about how to create an enterprise project, see Optical Character Recognition User Guide.

NOTE:

After an enterprise project is created, parameter transfer involves the following scenarios:

  • If a correct enterprise project ID is carried and the OCR service can be used properly, the bills are allocated to the enterprise project corresponding to the ID.
  • If an incorrect enterprise project ID is carried and the OCR service can be used properly, the enterprise project in the bills is allocated to Non-project.
  • If no enterprise project ID is carried and the OCR service can be used properly, the enterprise project in the bills is allocated to Non-project.
Table 4 Request body parameters

Parameter

Mandatory

Type

Description

image

No

String

Configure either this parameter or url. Base64-encoded image file. The image file has a size limit of 10 MB. No side of the image can be smaller than 15 or larger than 8,192 pixels. Only images in JPEG, JPG, PNG, BMP, or TIFF format can be recognized.

url

No

String

Configure either this parameter or image. Image URL. Currently, the following URLs are supported:

Image URL. Currently, the following URLs are supported:

  • Public HTTP/HTTPS URL
  • URL provided by OBS. You need to be authorized to use OBS data, including service authorization, temporary authorization, and anonymous public authorization.
NOTE:
  • The API response time depends on the image download time. If the image download takes a long time, the API call will fail.
  • Ensure that the storage service where the image to be detected resides is stable and reliable. OBS is recommended for storing image data.

country_region

No

Array of strings

Code of the country or region where a certificate is issued. The name must comply with ISO 3166-1 alpha-2 codes. This parameter is optional. You can enter one or more country/region codes. After this parameter is specified, the service identifies cards only in the specified country or region. If this parameter is left blank, all supported cards are identified. It is recommended that this field be filled in when the country/region is fixed or limited. For the list of supported countries and regions, see Table 1.

NOTE:

This parameter is mandatory when Vietnamese is recognized.

id_type

No

Array of strings

Certificate type. This parameter is optional. One or more types of documents are supported. If this parameter is specified, the service identifies only the documents of the specified type. If this parameter is left blank, all types of documents are identified by default. You are advised to configure this parameter if the document type is known. The following document types are supported:

  • PP: passport
  • DL: driving license
  • ID: identification card, which is an identity card issued by a country or region, such as an ID card, voter registration card, and social security card.

return_portrait_image

No

Boolean

Whether to return the portrait image (face image in the document). The value true indicates that the portrait image needs to be returned, and the value false indicates that the portrait image does not need to be returned.

Response Parameters

Status code: 200

Table 5 Response body parameter

Parameter

Type

Description

result

IdDocumentItem object

Recognition result

This parameter is not included when the API fails to be called.
Table 6 IdDocumentItem

Parameter

Type

Description

country_region

String

Code of the country or region where a certificate is issued. The code must be defined in ISO 3166-1 alpha-2 codes. For the list of supported countries and regions, see Table 1.

id_type

String

Document type. Value options are as follows:

  • PP: passport
  • DL: driving license
  • ID: identification card, which is an identity card issued by a country or region, such as an ID card, voter registration card, and social security card.

side

String

Front or back of an identity document. Value options are as follows:

  • front: front side of the document, which is typically the side that contains a portrait.
  • back: front is returned if a document has only one side.

first_name

String

First name

last_name

String

Last name

sex

String

Gender. Value options are as follows: M: male; F: female; X: third gender.

nationality

String

Nationality of the document holder

birth_date

String

Date of birth, in YYYY-MM-DD format

issue_date

String

Date of issue, in YYYY-MM-DD format

expiry_date

String

Expiration date, in YYYY-MM-DD format

document_number

String

Document number

address

String

Contact address of the holder

issuing_authority

String

Issuing authority

portrait_image

String

Base64 code of the head portrait on the document, which is optional

confidence

Object

Field confidence. The value is a decimal ranging from 0 to 1. A larger value indicates more reliable recognition results.

Status code: 400

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Error code of a failed API call. For details, see Error Codes. This parameter is not included when the API is successfully called.

error_msg

String

Error message when the API call fails. This parameter is not included when the API is successfully called.

Example Requests

  • endpoint is the request URL for calling an API. Endpoints vary depending on services and regions. For details, see Endpoints.

    For example, ID Document OCR is deployed in the CN-Hong Kong region. The endpoint is ocr.ap-southeast-1.myhuaweicloud.com or ocr.ap-southeast-1.myhuaweicloud.cn. The request URL is https://ocr.ap-southeast-1.myhuaweicloud.com/v2/{project_id}/ocr/id-document. project_id is the project ID. For details about how to obtain the project ID, see Obtaining a Project ID.

  • For details about how to obtain a token, see Making an API Request.
  • Request example (Method 1: Use the image Base64 string.)
    POST https://{endpoint}/v2/{project_id}/ocr/id-document

{
  "image" : "/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAA...",
  "country_region" : "ALB",
  "id_type" : "PP"
}
  • Request example (Method 2: Use the image URL.)
    POST https://{endpoint}/v2/{project_id}/ocr/id-document

{
  "url" : "https://BucketName.obs.xxxx.com/ObjectName",
  "country_region" : "ALB",
  "id_type" : "PP"
}

Example Responses

Status code: 200

Example of a successful response

{
  "result" : {
    "country_region" : "ALB",
    "id_type" : "PP",
    "side" : "front"
  }
}

Status code: 400

Example of a failed response

{
  "error_code" : "AIS.0103",
  "error_msg" : "The image size does not meet the requirements."
}

Status Codes

Status Code

Description

200

Success response

400

Failure response

Error Codes

For details about error codes, see Error Codes.

Parent topic: APIs