Parse QR Info

Parses the raw QR payload from a Vietnamese national ID card into structured fields, including a decomposed address hierarchy. Use it when your client already has the decoded QR string and needs it normalized without submitting an image.

Endpoint

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

{
  "raw_qr": "string"
}

Parameters:

Param	Type	Required	Default	Description
raw_qr	string	Yes	—	Raw QR code string from the card. Pipe-separated in order: Identity Number (12 digits) | Old Identity Number (9 digits or empty) | Full Name | Date of Birth (DDMMYYYY) | Gender (Nam/Nữ) | Native Place | Issue Date (DDMMYYYY).

Returns: ParseQrInfoResponse

Sample Request

curl --location '<BASE_URL>/v1/parse_qr_info_sync' \
  --header 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  --header 'X-TV-Timestamp: <TIMESTAMP>' \
  --header 'Content-Type: application/json' \
  --data '{
    "raw_qr": "001xxxxxxxxx|xxxxxxxxx|Nguyễn Văn A|12121990|Nam|Tổ 1, Phường Bến Nghé, Quận 1, TP. Hồ Chí Minh|01012021"
  }'

Response

{
  "success": true,
  "code": 0,
  "message": "Success",
  "data": {
    "request_id": "f48085e4-3ae4-40bb-b0e1-9b2c72575bc1",
    "status": "success",
    "qr": {
      "parsed": [
        { "field": "id", "value": "001xxxxxxxxx", "confidence_score": 1.0, "confidence_verdict": "" },
        { "field": "name", "value": "Nguyễn Văn A", "confidence_score": 1.0, "confidence_verdict": "" },
        { "field": "dob", "value": "12/12/1990", "confidence_score": 1.0, "confidence_verdict": "" },
        { "field": "address_level_1_(city)", "value": "TP. Hồ Chí Minh", "confidence_score": 1.0, "confidence_verdict": "" }
      ],
      "raw": "001xxxxxxxxx|xxxxxxxxx|Nguyễn Văn A|12121990|Nam|Tổ 1, Phường Bến Nghé, Quận 1, TP. Hồ Chí Minh|01012021"
    }
  },
  "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.qr.raw	string	The raw QR string as submitted.
data.qr.parsed	ParsedField[]	The structured fields extracted from the QR payload.

ParsedField

Field	Type	Description
field	string	Field name — see the table below.
value	string	Extracted value.
confidence_score	float	Always 1.0 for QR, which is encoded rather than recognized.
confidence_verdict	string	Empty for QR-sourced fields.

Fields returned

The seven pipe-separated inputs, plus a decomposed address hierarchy derived from the native place:

Field	Type	Description
id	string	NID number, 12 digits.
id_1	string	Legacy CMND number, 9 digits.
name	string	Full name.
dob	string	Date of birth, normalized to DD/MM/YYYY.
gender	string	Nam or Nữ.
native_place	string	Place of origin as printed.
issue_date	string	Issue date, normalized to DD/MM/YYYY.
address_level_1_(city)	string	Province or centrally-managed city.
address_level_1_(city)_code	string	Provincial administrative code.
address_level_2_(district)	string	District.
address_level_2_(district)_code	string	District administrative code.
address_level_3_(ward)	string	Ward, commune or township.
address_level_3_(ward)_code	string	Ward administrative code.
address_level_4	string	Hamlet or residential group.

Dates arrive as DDMMYYYY and come back as DD/MM/YYYY.

Errors

Validation of the QR payload has its own 2007xxx code range:

Code	Message
2007001	Invalid QR identity number.
2007002	Invalid QR old identity number.
2007003	Invalid QR date of birth.
2007004	Invalid QR gender value.
2007005	Invalid QR issue date.
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
invalid_qr_identity_number	Identity number must be exactly 12 digits.
invalid_qr_old_identity_number	Old identity number must be empty or exactly 9 digits.
invalid_qr_date_of_birth	Date of birth format is invalid or the date does not exist. Expected format DDMMYYYY.
invalid_qr_gender_value	Gender must be either Nam (male) or Nữ (female).
invalid_qr_issue_date	Issue date format is invalid or the date does not exist. Expected format DDMMYYYY.
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.
internal_server_error	Some unexpected error occurs while processing the request.

Next Steps

• Read ID Card Info — extract the same fields from an image instead
• Detect ID Card Tampering — cross-check QR against OCR and MRZ