Skip to main content

National ID Verification API

This document highlights the National ID Verification API details.

API Description​

Objective​

The National ID Verification API allows you to verify and extract information from national ID cards. It is used to detect and validate Vietnam National IDs in images or PDF files.

API URL​

https://vnm-docs.hyperverge.co/v2/nationalID

API Endpoint​

nationalID

Overview​

The API is RESTful, utilizing standard HTTP verbs and status codes. Responses are provided in JSON format, and all images and files must be uploaded as form-data via a POST request.

Authentication​

To access the API, you must obtain a unique pair of application ID (appId) and application key (appKey) from HyperVerge for identity verification.

Method - POST​

Headers​

ParameterMandatory or OptionalDescriptionAllowed Values
content-type MandatoryThis parameter defines the media type for the request payloadapplication/json
appId MandatoryThe application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.This should be a unique value.
appKey MandatoryThe application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.This should be a unique value.
transactionIdMandatoryA unique identifier for tracking a complainant journeyThis should be both unique and easily associated with the complainant's journey in your application(s)

Input​

The following table outlines the parameters required in the API's request body:

ParameterDescriptionMandatory or OptionalAllowed ValuesDefault Value
imageThe image or PDF file containing the national IDMandatoryNot ApplicableNot Applicable

Request​

The following code snippet demonstrates a standard curl request for the API:

curl --location --request POST 'https://vnm-docs.hyperverge.co/v2/nationalID' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--form 'image=@"<path_to_image_file>"'

Success Response​

The following JSON code snippet demonstrates a success response from the API:

{
  "status": "success",
  "statusCode": "200",
  "requestId": "<Request_ID>",
  "transactionId": "<Transaction_ID>",
  "result": {
    "details": [
      {
        "type": "cmnd_old_front/cmnd_old_back/cmnd_new_front/cccd_front/cmnd_new_cccd_back/cccd_chip_front/cccd_chip_back",
        "fieldsExtracted": {
          "name": {
            "to-be-reviewed": "no",
            "value": "<Name of the User>"
          },
          "dob": {
            "to-be-reviewed": "no",
            "value": "<Date_of_Birth>"
          },
          "idNumber": {
            "to-be-reviewed": "no",
            "value": "<Card_ID>"
          },
          "permanentAddress": {
            "to-be-reviewed": "no",
            "value": "<Address>",
            "province": "<Province>",
            "provinceCode": "<Province_Code>",
            "district": "<District>",
            "districtCode": "<District_Code>",
            "ward": "<Ward>"
          },
          "province": {
            "value": "<Province>"
          },
          "homeTown": {
            "value": "<Home_Town>",
            "to-be-reviewed": "yes"
          },
          "nationality": { 
            "value": "Việt Nam <Only_for_Citizen_ID>",
            "to-be-reviewed": "no"
          },
          "gender": {
            "value": "F/M <Only for New National ID or Citizen ID>",
            "to-be-reviewed": "no"
          },
          "doe": {
            "value": "12-08-2027 <Only for New National ID or Citizen ID>",
            "to-be-reviewed": "no"
          }
        },
        "alignedDocumentURL": "<Cropped & aligned document>",
        "ocrMatchWithUserInput": {
          "name": "yes",
          "dob": "yes",
          "idNumber": "yes",
          "all": "yes"
        },
        "ruleChecks": {
          "idProvinceCodeInvalid": {
            "value": "yes",
            "to-be-reviewed": "no"
          },
          "idDOBGenderCodeInvalid": {
            "value": "yes",
            "to-be-reviewed": "no"
          },
          "idNumberLengthMismatch":{
            "value": "yes",
            "to-be-reviewed": "no"
          },
          "expiredID": {
            "value": "yes",
            "daysToExpire": -45
          }
        },
        "tamperChecks": {
          "photoTampered": {
            "to-be-reviewed": "yes",
            "value": "no"
          },
          "idNumberTampered": {
            "to-be-reviewed": "yes",
            "value": "no"
          },
          "dobTampered": {
            "to-be-reviewed": "yes",
            "value": "no"
          },
          "emblemTampered": {
            "to-be-reviewed": "yes",
            "value": "no"
          },
          "dobColonTampered": {
            "to-be-reviewed": "yes",
            "value": "no"
          }
        },
        "qualityChecks": {
          "glare": {
            "to-be-reviewed": "yes",
            "value": "no"
          },
          "blur": {
            "to-be-reviewed": "no",
            "value": "no"
          },
          "faceNotDetected": {
            "to-be-reviewed": "no",
            "value": "no"
          },
          "cornerCut": {
            "to-be-reviewed": "no",
            "value": "yes"
          },
          "blackAndWhite": {
            "to-be-reviewed": "yes",
            "value": "no"
          },
          "capturedFromScreen": {
            "to-be-reviewed": "no",
            "value": "yes"
          }
        }
      }
    ],
    "summary": {
      "action": "manualReview",
      "details": [
        {
          "code": "003",
          "message": "National ID Number validation failed"
        }
      ]
    }
  }
}

Success Response Details​

The Summary Object​

The summary object suggests the final action for the user's application.

  • The configuration is customizable. It can be changed based on your preferences at anytime of your integration and after go-live.
  • The configuration is hosted in the backend and not in the SDK/frontend.
  • New features can be supported immediately, thus not requiring app release at your end.

The following code samples are the 3 types of actions responses that you will find in the response.

This is the response where the application is approved for further processing.

"summary": {
    "action": "pass",
    "details": []
}

Error Response​

The following are the error responses from the API:

{
"status": "failure",
"statusCode": "422",
"error": "Vietnam National ID Not Detected",
"requestId": "1600422710095-2289c5f4-44a9-4dd1-b1db-1236763",
"transactionId":"12345",
"result": {
   "summary": {
      "action": "fail",
      "details": [
      {
         "code": "003",
         "message": "Vietnam National ID Not Detected"
      }
      ]
   }
}
}

Error Response Details​

A failure or error response from the module contains a failure status, with a relevant status code and error message. The following table lists all error responses:

Status CodeError MessageError Description
422Vietnam National ID Not DetectedWhen the AI model fails to detect a National ID in the image sent.
400API call requires at least one input imageThis error is returned when 'image' is not sent in the API call.
400API call handles only upto 2 imagesThis error is returned when more than 2 images are sent in the API call.
400TransactionId not detectedThis error is returned when 'transactionId' is not sent in request headers.
400image size cannot be greater than 6MBThe maximum size of input image is 6MB. Crossing this will result in this error.
429Rate limit exceededThis error occurs when the number of transactions per minute exceeds the limit set for your credentials.
500/501Internal Server ErrorThere is an issue with the service. Kindly contact the HyperVerge Team for support.
503Server busyThis happens when there is an overload on HyperVerge's server.

Fields Extracted​

Document Type"type" in responseList of Fields
Old National ID - Front Sidecmnd_old_frontidNumber, name, dob, province, homeTown, permanentAddress
Old National ID - Back Sidecmnd_old_backdoi, placeOfIssue, doe, ethnicity
New National ID - Front Sidecmnd_new_frontidNumber, name, gender, dob, permanentAddress, doi, doe, province, homeTown, ethnicity
Citizen ID - Front Sidecccd_frontidNumber, name, gender, dob, permanentAddress, doi, doe, province, homeTown, nationality
New National ID/Citizen ID - Back Sidecmnd_new_cccd_backdoi, placeOfIssue
Chip Citizen ID Front Sidecmnd_new_cccd_backidNumber, name, gender, dob, permanentAddress, doe, province, homeTown, nationality
Chip Citizen ID Back Sidecccd_chip_backdoi, placeOfIssue
CC24 Chip ID Front Sidecc24_frontidNumber, name, dob, gender, nationality
CC24 Chip ID Back Sidecc24_backdoi, placeOfIssue, doe, province, homeTown, permanentAddress

Quality Checks​

Following are the quality checks supported by the National ID API:

  • Blur Detection: Detect if the fields in the National ID image are blurred.

  • Glare Detection: Detect if there is any glare on the image due to flash light etc.

  • Face Detection: Detect if there is a face present on the card. national_id_ocr_api

  • Black & White Detection: Detect if National ID is a black & white photocopy. national_id_ocr_api

  • Captured-From-Screen: Detect if National ID is real or captured by showing image on a mobile phone or laptop. national_id_ocr_api

  • Partial ID Detection: Detect if any edge of the National ID image has been cut off or if there is any obstruction on the card. national_id_ocr_api national_id_ocr_api

Quality Check Details​

Quality Check TypeAPI ParameterPrerequisite ParameterDocuments SupportedResponse Field
Blur CheckblurCheckqualityCheckcmnd_old_front, cmnd_new_front, cccd_front, cmnd_old_back, cmnd_new_cccd_back, cccd_chip_front, cccd_chip_back, cc24_front, cc24_backblur
Glare CheckglareCheckqualityCheckcmnd_old_front, cmnd_new_front, cccd_front, cmnd_old_back, cmnd_new_cccd_back, cccd_chip_front, cccd_chip_back, cc24_front, cc24_backglare
Face CheckfaceCheck-cmnd_old_front, cmnd_new_front, cccd_front, cmnd_old_back, cmnd_new_cccd_back, cccd_chip_front, cccd_chip_back, cc24_front, cc24_backfaceNotDetected
Black & White CheckcheckBlackWhite-cmnd_old_front, cmnd_new_front, cccd_front, cmnd_old_back, cmnd_new_cccd_back, cccd_chip_front, cccd_chip_back, cc24_front, cc24_backblackAndWhite
Captured From Screen ChecklivenessCheckfraudCheckcmnd_old_front, cmnd_new_front, cccd_front, cmnd_old_back, cmnd_new_cccd_back, cccd_chip_front, cccd_chip_back, cc24_front, cc24_backcapturedFromScreen
Partial ID CheckpartialIdCheckqualityCheckcmnd_old_front, cmnd_new_front, cccd_front, cmnd_old_back, cmnd_new_cccd_back, cccd_chip_front, cccd_chip_back, cc24_front, cc24_backpartialID

Tamper Check Details​

national_id_ocr_api

The following table lists all the ID Card tamper checks supported by the National ID API.

Type of CheckObjectiveParameterDocuments SupportedResponse Field
Enable Text Forgery and Photo Forgery CheckforgeryCheck
User Photo Tamper CheckIt checks if the user photo on the image is tampered.photoForgeryCheck
Prerequisite parameter: forgeryCheck		cmnd_old_front, cmnd_new_front, cccd_front, cccd_chip_front, cc24_frontphotoTampered
National ID Number Tamper CheckIt checks if the National ID number field on the image is tampered.textForgeryCheck
Prerequisite parameter: forgeryCheck		cmnd_old_front, cmnd_new_front, cccd_frontidNumberTampered
Emblem Tamper CheckIt checks if the "National ID logo" is tampered (only for front side).emblemForgeryCheckcmnd_old_frontemblemTampered
Date of Birth Tamper CheckIt checks if the 'date of birth' field on the image is tampered.dobForgeryCheckcmnd_old_frontdobTampered
DOB Colon tamper CheckIt checks if the colon is present next to DOB field on the National ID.dobColonForgeryCheckcmnd_old_frontdobColonTampered

Rule Check Details​

national_id_ocr_api

The following table lists all the ID Card tamper checks supported by the National ID API.

Type of CheckObjectiveParameterDocuments SupportedResponse Field
ID Province Code ValidationIt checks if the province code in the National ID Number is valid It either verifies if the first two digits for an old NID or the first three digits for a new citizen ID is present in the list of province codes.checkProvinceMismatchcmnd_old_front, cmnd_new_front, cccd_front, cccd_chip_front, cc24_frontidProvinceCodeInvalid
YOB & Gender Code ValidationIt checks if the date of birth and the gender matches the code in the National ID number. This is only applicable for the new National or Citizen ID.enableGenderAndDOBMismatchcmnd_new_front, cccd_front,cccd_chip_frontidDOBGenderCodeInvalid
Date of expiry validationIt checks if the date of issue is past the date of expiry.expiryCheckcmnd_new_front, cccd_front, cc24_backexpiredID
ID Number Length CheckCheck if length of the ID number is correctidNumberLengthCheckcmnd_old_front, cmnd_new_front, cccd_front, cccd_chip_frontidNumberLengthCheck
MRZ tamper checkIt checks if the user photo on the image is tampered.mrzTamperCheckcccd_chip_back, cc24_backmrzTamperCheck

MRZ Tamper Check Details​

Details of the feature:

  • The fields, 'ID number', 'Name', 'Date of Birth', and 'Date of Expiry' from the MRZ are extracted as part of the OCR API call for the Chip ID and CC24 backside.
  • The first two lines of MRZ will be validated to check if it is authentic or tampered. The 3rd line is not validated as part of this check.
{
    "status": "success",
    "statusCode": "200",
    "result": {
      "details": [
          {
            "fieldsExtracted": {
                "placeOfIssue": {
                    "value": "CỤC TRƯỞNG CỤC CẢNH SÁT QUẢN LÝ HÀNH CHÍNH VỀ TRẬT TỰ XÃ HỘI",
                    "to-be-reviewed": "no"
                },
                "doi": {
                    "value": "10-03-2021",
                    "to-be-reviewed": "no"
                },
                "mrz":{             
                  "value":"IDVNM1630194589079163019458<<96305073F2305075VNM<<<<<<<<<<<8DO<<THI<HONG<MINH<<<<<<<<<<<<<<",
                  "idNumber":"123456789",
                  "dob":"07-05-1900",
                  "doe":"07-05-2023",
                  "name":"John Doe",
                  "nationality":"VNM"
                }
            },
            "ruleChecks":{
              "mrzTampered":{
                "value":"yes"
              }
          }
          "type": "cccd_chip_back"
          }
        ],
        "summary": {
          "action": "manualReview",
          "details": [
            {
              "code": "065",
              "message": "MRZ is tampered"
            }
          ]   
        }
    },
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
}
Was this helpful?
ON THIS PAGE
Ask AIBeta
Hi! How can I help?
Ask me anything about HyperVerge products, APIs, and SDKs.
Try asking: