Read ID Card Info

Extracts the printed and encoded fields from an ID card image — OCR text, the MRZ machine-readable zone, the QR code and, where available, NFC chip data — each with a confidence score.

Endpoint

POST /v1/read_id_card_info_sync
Content-Type: application/json

{
  "card_type": "vn.national_id",
  "image1": {
    "id": "2dc863d6-1f68-4c82-8380-dd34e4ed7da0",
    "base64": "",
    "label": "id_card.vn.national_id.front",
    "metadata": "{}"
  }
}

Parameters:

Param	Type	Required	Default	Description
card_type	string	Yes	—	The card type. See Usage Recommendations.
image1	ImageData	Yes	—	Image of the identity card's front side or back side.

ImageData

Param	Type	Required	Default	Description
id	string	No	—	ID of the image returned by Upload Image.
base64	string	No	—	Base64-encoded text of the image data.
label	string	No	—	Label of the image, as described in Usage Recommendations.
metadata	string_json	No	—	Key/value JSON string. Example: {"id":"<ID>","type":1}

Supply either id or base64, never both.

Sample Request

curl --location '<BASE_URL>/v1/read_id_card_info_sync' \
  --header 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  --header 'X-TV-Timestamp: <TIMESTAMP>' \
  --header 'Content-Type: application/json' \
  --data '{
    "card_type": "vn.national_id",
    "image1": {
      "id": "e94288e6-7ab5-4aeb-9608-8382f4ceb92f",
      "base64": "",
      "label": "id_card.vn.national_id.back",
      "metadata": "{}"
    }
  }'

Response

{
  "data": {
    "request_id": "09c1bf6b-2522-4202-b3e5-a2d63dc2d0ea",
    "status": "success",
    "card_information": [
      {
        "field": "name",
        "value": "NGUYỄN VĂN A",
        "confidence_score": 0.904328,
        "confidence_verdict": "SURE",
        "digit_confidence_scores": []
      }
    ],
    "image1": {
      "id": "2dc863d6-1f68-4c82-8380-dd34e4ed7da0",
      "card_box": {
        "top_left": { "x": 134, "y": 191 },
        "top_right": { "x": 946, "y": 191 },
        "bottom_left": { "x": 134, "y": 710 },
        "bottom_right": { "x": 946, "y": 710 }
      },
      "ocr": {
        "parsed": [
          {
            "field": "id",
            "value": "001xxxxxxxxx",
            "confidence_score": 0.90224093,
            "confidence_verdict": "SURE",
            "digit_confidence_scores": []
          }
        ],
        "char_probs": [],
        "confidence_score": 0,
        "entropy": 0,
        "group": 0,
        "label": 0,
        "line": 0,
        "text": ""
      },
      "mrz": { "parsed": [], "char_probs": [], "confidence_score": 0, "entropy": 0, "group": 0, "label": 0, "line": 0, "text": "" },
      "qr": { "parsed": [], "char_probs": [], "confidence_score": 0, "entropy": 0, "group": 0, "label": 0, "line": 0, "text": "" },
      "nfc": null
    },
    "image2": null
  },
  "errors": []
}

Field	Type	Description
data.request_id	string	Request ID; quote it to CAKE Support when checking logs.
data.status	string	success or failure.
data.card_information	ParsedField[]	Consolidated card fields, merged across every available source.
data.image1	ImageResult	Per-source extraction result for the first image.
data.image2	ImageResult	Result for the second image, or null when not supplied.

ImageResult

Field	Type	Description
id	string	ID of the analysed image.
card_box	CardBox	Corner coordinates of the detected card, each corner { "x": int, "y": int }.
ocr	ExtractionResult	Fields read from the printed card surface.
mrz	ExtractionResult	Fields read from the machine-readable zone.
qr	ExtractionResult	Fields read from the QR code.
nfc	ExtractionResult	Fields read from the NFC chip, or null when no chip data was supplied.

ExtractionResult

Field	Type	Description
parsed	ParsedField[]	The structured fields extracted from this source.
text	string	Raw text read from this source.
char_probs	float[]	Per-character confidence probabilities.
confidence_score	float	Overall confidence for this source.
entropy	float	Entropy of the recognition result.
group	int	Internal grouping index.
label	int	Internal label index.
line	int	Line index within the source.

ParsedField

Field	Type	Description
field	string	Field name, e.g. id, name.
value	string	Extracted value.
confidence_score	float	Confidence in the extracted value, range 0–1.
confidence_verdict	string	Categorical confidence, e.g. SURE.
digit_confidence_scores	float[]	Per-digit confidence for numeric fields.

INFO

Do not treat a low-confidence field as verified data. Gate acceptance on confidence_verdict and confidence_score, and route anything below your threshold to manual review — especially the ID number and date of birth.

Errors

Code	Message
2001010	Access ID not found.
401100	You are not authorized to perform the action.
4001000	Input parameter violates a constraint.
4001001	The X-TV-Timestamp header is expired, need a newer one.
5001000	Some unexpected error occurs while processing the request.

Code	Description
access_denied_exception	You are not authorized to perform the action.
invalid_parameter_exception	Input parameter violates a constraint.
request_time_too_skewed	The X-TV-Timestamp header is expired, need a newer one.
image_not_found_exception	The image ID is not found in DB.
rate_limit_exception	The number of requests exceeded your throughput limit.
internal_server_error	Some unexpected error occurs while processing the request.

Next Steps

• Detect ID Card Tampering — cross-check OCR, MRZ and QR for signs of forgery
• Compare Faces — match the card portrait against the selfie