ID Card · Standard API · eKYC Core
Detect ID cards
Finds the identity cards in an image and returns each card's label and the coordinates of its four corners.
Request
Clients can provide image data to the TrustVision API by specifying the ID the image by using upload API, or by sending the image data as base64-encoded text.
| Name | Type | Required | Description |
|---|---|---|---|
card_type | string | Required | type of identity card, described at Card type table |
image | ImageData | Required | image of the identity card's front side |
- If you use
base64,labelandmetadata, omit parameterid. - If you use
id(resultidis returned from Upload Image API), omit parameterbase64,labelandmetadata.
The
ImageDatashape —id,base64,labelandmetadata— is defined once on Common objects.
{
"card_type": string,
"image": {
"id": string,
"base64": string,
"label": string,
"metadata": string_json,
}
}
Sample request
curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/detect_id_cards_sync \
-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",
"image": {
"id": "a4facba3-334b-41fb-97e3-4766cb70ae29"
}
}
'
Response
data.image.cards lists every card found in the image, each with its card_label and the corner coordinates of its card_box. The data.status is either "success" or "failure" depending on whether the request has been successfully processed or not.
{
"data": {
"request_id": string,
"status": string, // "success" or "failure"
"image": {
"id": string,
"cards": [
{
"transformed_image_id": string, // optional, in case the card is transformed (setting `enable_create_image` is True)
"card_label": string, // see below
"card_box": {
"top_left": { "x": float, "y": float },
"top_right": { "x": float, "y": float },
"bottom_left": { "x": float, "y": float },
"bottom_right": { "x": float, "y": float },
},
},
... // other cards in the image
],
},
"request_id": string // return request id to the client and can use request-id to check logs.
},
"errors": [
{
"code": string,
"message": string,
"detail": {
"field": string, // optional, which parameter is invalid.
... // any other information that can be useful for client
},
},
... // other errors
]
}
Label and type of identity card, described at Card type table:
card_label | Description |
|---|---|
vn.cmnd_old.front | The front side of Vietnam national ID old version (Chứng minh nhân dân cũ) |
vn.cmnd_old.back | The back side of Vietnam national ID old version (Chứng minh nhân dân cũ) |
vn.cmnd_new.front | The front side of Vietnam national ID new version (Chứng minh nhân dân mới) |
vn.cmnd_new.back | The back side of Vietnam national ID new version (Chứng minh nhân dân mới) |
vn.cccd.front | The front side of Vietnam national ID latest version (Căn cước công dân) |
vn.cccd.back | The back side of Vietnam national ID latest version (Căn cước công dân) |
vn.cccd_new.front | The front side of Vietnam national ID latest version (Căn cước công dân gắn chip) |
vn.cccd_new.back | The back side of Vietnam national ID latest version (Căn cước công dân gắn chip) |
vn.passport.front | Main page of Vietnam passport |
vn.passport_new.front | Main page of Vietnam passport ne |
vn.mid.front | Front side of Vietnam military ID card |
vn.mid.back | Back side of Vietnam military ID card |
in.aadhaar.front | Front side of India Aadhaar card |
in.aadhaar.back | Back side of India Aadhaar card |
in.aadhaar_letter.back | Back side of India Aadhaar letter |
in.voter.front | Front side of India Voter card |
in.voter.back | Back side of India Voter card |
in.pan.front | Front side of India PAN card |
in.pan.back | Back side of India PAN card |
in.passport.back | Back side of India passport |
in.dl.front | Front side of India driving license |
ph.ump.front | The front side of Philippines UMP |
ph.tin.front | The front side of Philippines TIN |
ph.dl.front | The front side of Philippines DL |
ph.sss.front | The front side of Philippines SSS |
ph.nid.front | The front side of Philippines NID |
ph.passport.front | The front side of Philippines passport |
ph.postal.front | The front side of Philippines postal |
ph.philhealth.front | The front side of Philippines philhealth |
ph.prc.front | The front side of Philippines PRC |
ph.loyalty.front | The front side of Philippines loyalty |
mx.national_id | Any of the Mexico national ID versions |
mx.ine_type_e | Instituto Nacional Electoral type e Card |
mx.ine_type_f | Instituto Nacional Electoral type f card |
mx.ine_type_g | Instituto Nacional Electoral type g card |
mx.ine_type_h | Instituto Nacional Electoral type h card |
One Vietnamese chip ID card detected in the image comes back like this:
{
"data": {
"request_id": "f77bf948-fce3-48f3-b61c-396e4cd9a89b",
"status": "success",
"image": {
"id": "854322f0-eb49-4bd6-b870-050fcc088d10",
"cards": [
{
"card_box": {
"bottom_left": {
"x": 102.62150720786303,
"y": 679.5154545297846
},
"bottom_right": {
"x": 996.863339483738,
"y": 661.6368409626185
},
"top_left": {
"x": 90.52290163561702,
"y": 110.761657032324
},
"top_right": {
"x": 981.4022462964058,
"y": 101.39770825190935
}
},
"card_label": "vn.cccd_new.front",
"transformed_image_id": ""
}
]
}
}
}
Failure codes
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.