/ocr/idcard

1.API Specification
2.Request Params
3.Response Params
4.Error Codes
5.Sample

1.API Specification

This API is used to recognize ID card of Vietnam, and extract the key information.

Image spec

1. Format: JPG(JPEG), PNG, e-aadhaar(PDF)
2. Between 128*128 and 6000*6000 (pixels), Recommended resolution: 1280*1280
3. File size: no larger than 5 MB

Request Method

POST

Request URL

https://cloudapi.vietnam.accuauth.com/ocr/idcard

Debugging Tool

Debugging Tool

2.Request Params

2.1 Request Header

Parameter Type Required Description
X-DF-API-ID string Yes For API credentials，Please visit API Request
X-DF-API-SECRET string Yes For API credentials，Please visit API Request

2.2 Request Body

Fields Type Description
optional file file Binary data of the image
optional image_base64 string Base64 encoded data of image

Either parameter file or image_base64 must be provided as a request parameter.

You MUST add image stream to multipart/form-data section of POST message when using file parameter.

3.Response Params

Fields Type Description
request_id string Unique id of each request
status string Response status, OK if request success, other if failed; See Error Codes for details
results array The array of card ocr results，See results belowed for details
Elements in results:
Fields Type Description
card_side string The side of card: front or back
card_type string The type of card: CMND, CCCD, CC or DL
card_info object The key infomation of card
Elements in the card_info
  • Front side of CMND card info:
Fields Type Description
id_number string ID card number
name string Name (In Vietnamese)
birthday string Date of birth
family_origin string Family Origin (In Vietnamese)
address string Address (In Vietnamese)
state string State in the address (In Vietnamese)
city string City in the address (In Vietnamese)
district string District in the address (In Vietnamese)
subdistrict string Sub-district in the address (In Vietnamese)
  • Back side of CMND card info:
Fields Type Description
ethnicity string Ethnicity of the person (In Vietnamese)
religion string Religion of the person (In Vietnamese)
issue_day string Issue day of the card
issue_month string Issue month of the card
issue_year string Issue year of the card
  • Front side of CCCD card info:
Fields Type Description
id_number string ID card number
name string Name (In Vietnamese)
birthday string Date of birth
gender string Gender (In Vietnamese), Nam = MALE, Nữ= FEMALE
gender_s string Formatted gender: M(male) or F(Female)
nationality string Nationality (In Vietnamese)
family_origin string Family Origin (In Vietnamese)
address string Address (In Vietnamese)
state string State in the address (In Vietnamese)
city string City in the address (In Vietnamese)
district string District in the address (In Vietnamese)
subdistrict string Sub-district in the address (In Vietnamese)
expiry_date string Expiry date of the card
  • Back side of CCCD card info:
Fields Type Description
issue_day string Issue day of the card
issue_month string Issue month of the card
issue_year string Issue year of the card
code_line1 string code line 1
code_line2 string code line 2
code_line3 string code line 3
  • Front side of CC card info:
Fields Type Description
id_number string ID card number
name string Name (In Vietnamese)
birthday string Date of birth
gender string Gender (In Vietnamese), Nam = MALE, Nữ= FEMALE
gender_s string Formatted gender: M(male) or F(Female)
nationality string Nationality (In Vietnamese)
  • Back side of CC card info:
Fields Type Description
issue_date string Issue date of the card, in day/month/year format
issue_date_s string Formated issue date of the card, in day/month/year format
place_of_birth string Place of birth
place_of_residence string Place of residence
expiry_date string Expiry date of the card, in day/month/year format
expiry_date_s string Formated expiry date of the card, in day/month/year format
code_line1 string code line 1
code_line2 string code line 2
code_line3 string code line 3
  • Front side of DL card info:
Fields Type Description
id_number string ID card number
name string Name (In Vietnamese)
birthday string Date of birth, in the format of day/month/year
dl_code string DL code
nationality string Nationality (In Vietnamese)
address string Address (In Vietnamese)
expiry_date string Expiry date of the card, in the format of day/month/year, a special value Không thời hạn means permanent
Response Syntax
  • Front side of CMND card
{
  "request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e",
  "status": "OK",
  "results": [{
     "card_side": "front",
     "card_type": "CMND",
     "card_info":{
        "id_number": "**********",
        "name": "**********",
        "birthday": "26-12-1993",
        "family_origin": "T**********",
        "address": "**********",
        "state": "Bắc Ninh",
        "city": "Bắc Ninh",
        "district": "",
        "subdistrict": "Vũ Ninh"
      }
  }]
}
  • Back side of CMND card
{
  "request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e",
  "status": "OK",
  "results": [{
     "card_side": "back",
     "card_type": "CMND",
     "card_info":{
        "ethnicity": "*****",
        "religion": "*****",
        "issue_day": "14",
        "issue_month": "02",
        "issue_year": "2012"
      }
  }]
}
  • Front side of CCCD card
{
  "request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e",
  "status": "OK",
  "results": [{
     "card_side": "front",
     "card_type": "CCCD",
     "card_info":{
       "id_number": "**********",
       "name": "**********",
       "birthday": "01/01/1985",
       "gender": "Nam",
       "gender_s": "M",
       "nationality": "Việt Nam",
       "family_origin": "***************",
       "address": "***************",
       "state": "Tha*****á",
       "city": "",
       "district": "T*****á",
       "subdistrict": "Th*****u",
       "expiry_date": "01/01/2025"
      }
  }]
}
  • Back side of CCCD card
{
  "request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e",
  "status": "OK",
  "results": [{
     "card_side": "back",
     "card_type": "CCCD",
     "card_info":{
        "issue_day": "14",
        "issue_month": "02",
        "issue_year": "2012",
        "code_line1": "IDVNM1690022158xxxxxxx",
        "code_line2": "6909013F290xxxxxxxx",
        "code_line3": "PHAM<<THIxxxxxxxx"
      }
  }]
}
  • Front side of CC card
{
    "request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e",
    "status": "OK",
    "results": [
        {
            "card_info": {
                "birthday": "05/12/1983",
                "gender": "Nữ",
                "gender_s": "F",
                "id_number": "0791930*****",
                "name": "PHAN HỒNG *****",
                "nationality": "Việt Nam"
            },
            "card_side": "front",
            "card_type": "CC"
        }
    ]
}
  • Front side of DL card
{
    "request_id": "TIDe3faaf76f1b74fffb50fcab80cc89ef0",
    "results": [
        {
            "card_info": {
                "address": "****. Phù Lưu Tế, H. Mỹ Đức, ****",
                "birthday": "16/02/1995",
                "dl_code": "A1",
                "expiry_date": "30/12/2025",
                "id_number": "01116301*****",
                "name": "NGUYỄN THI ******",
                "nationality": "VIỆT NAM"
            },
            "card_side": "front",
            "card_type": "DL"
        }
    ],
    "status": "OK"
}

4.Error Codes

Common error codes of this API:

Http Status Code Status field Description
400 INVALID_ARGUMENT Request parameter is invalid
400 DETECTION_FAILED Detect image failed
401 UNAUTHORIZED Unauthorized or access is denied
401 KEY_EXPIRED Your API ID has expired
403 NO_PERMISSION You are not authorized to use this API
403 OUT_OF_QUOTA API calls quota exceeded
403 RATE_LIMIT_EXCEEDED API request frequency exceeds the limit
404 NOT_FOUND Requested API cannot be found
500 INTERNAL_ERROR Internal server error

Comment: Please see the reason field for details when the above 40X error occurred

Response Syntax
{
  "status": "INVALID_ARGUMENT",
  "reason": "must specify 'file' or 'image_base64' argument",
  "request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e"
}

5.Sample

results matching ""

    No results matching ""