ID Card · Standard API · eKYC Core
Read QR info
POST/v1/read_qr_info
Parses the raw text read from the QR code on an identity card into named card fields.
Request
| Name | Type | Required | Description |
|---|---|---|---|
raw_text | string | Required | the raw text read from QR |
card_type | string | Optional | type of identity card, described at Card type table |
{
"card_type": string,
"raw_text": string
}
Sample request
curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/read_qr_info \
-H 'Authorization: TV <YOUR ACCESS KEY>:<CREATED SIGNATURE>' \
-H 'X-TV-Timestamp: 2019-04-21T18:00:15+07:00' \
-H 'Content-Type: application/json' \
-d \
'
{
"card_type": "vn.national_id",
"raw_text": "012345678910||NGUYỄN VĂN A|01012001|Nam|132 Hàm Nghi, Phường Bến Thành, Quận 1, TP.Hồ Chí Minh|25072022"
}
'
Response
data.card_information carries the merged and normalized information read from the QR text. The data.status is either "success" or "failure" depending on whether the request has been successfully processed or not.
{
"data": {
"request_id": string, // ID of the request
"status": string, // "success" or "failure"
"card_information": [ // merged and normalized information from QR
{
"field": string, // field name ("identity_number", "full_name", "first_name", "middle_name", "last_name", "birth_date", "address_level_1_(city)", "address_level_1_(city)_code",...)
"value": string, // value of the field ("123456789", "Sohit Gour", "1998-06-23")
"confidence_verdict": string, // verdict of value ("SURE", "UNSURE", ""), empty mean Not Available. This field is shown if client enable 'enable_evaluate_confidence'
"confidence_score": float, // confidence score of predict value. This field is shown if client enable 'enable_evaluate_confidence'
},
... // other pair of card information
],
"request_id": string // return request id to the client and can use request-id to check logs.
},
"errors": [
{
"code": string, // "unexpected_error", "image_too_dark", "image_too_bright", ...
"message": string, // message to clarify the error code
"detail": {
... // any information to help trace and debug
}
},
... // other errors
]
}
A parsed Vietnamese chip ID card QR code comes back like this:
{
"data": {
"card_information": [
{
"confidence_score": 1,
"confidence_verdict": "SURE",
"field": "id",
"value": "012345678910"
},
{
"confidence_score": 1,
"confidence_verdict": "SURE",
"field": "name",
"value": "NGUYỄN VĂN A"
},
{
"confidence_score": 1,
"confidence_verdict": "SURE",
"field": "dob",
"value": "01/01/2001"
},
{
"confidence_score": 1,
"confidence_verdict": "SURE",
"field": "gender",
"value": "NAM"
},
{
"confidence_score": 1,
"confidence_verdict": "SURE",
"field": "address",
"value": "132 HÀM NGHI, PHƯỜNG BẾN THÀNH, QUẬN 1, TP.HỒ CHÍ MINH"
},
{
"confidence_score": 1,
"confidence_verdict": "SURE",
"field": "expiry_date",
"value": "01/01/2026"
},
{
"confidence_score": 1,
"confidence_verdict": "SURE",
"field": "issue_date",
"value": "25/07/2022"
},
...,
],
"status": "success"
"request_id": "dfdef016-e89b-4da4-ae17-5844f909c947"
}
}
Failure codes
If the data.status is "failure", the "errors" field will tell you why it failed.
| Error code | Description | Supported countries |
|---|---|---|
invalid_raw_text | the input raw text from QR is invalid | all |
In case of any other errors, the data field will be empty, and the server sends one of following HTTP status code with error code:
| HTTP code | Error code | Description |
|---|---|---|
401 | access_denied_exception | You are not authorized to perform the action. |
400 | invalid_parameter_exception | Input parameter violates a constraint. |
400 | request_time_too_skewed | The X-TV-Timestamp header is expired, need a newer one. |
404 | image_not_found_exception | The image ID is not found in DB. |
404 | request_not_found_exception | The request ID is not found when polling result by id |
408 | request_timeout_exception | Request takes too long to process |
429 | rate_limit_exception | The number of requests exceeded your throughput limit. |
500 | internal_server_error | Some unexpected error occurs while processing the request |
The codes above are the ones documented for this endpoint. Response errors on the Overview lists the codes for the eKYC Core surface as a whole — the two lists do not match on every endpoint.