Verify ID Card Sanity

Checks the quality of one or two ID card images and returns a verdict such as good, image1_not_qualified or photocopied. Run it before Read ID Card Info, Detect ID Card Tampering or Compare Faces — a poor-quality card image degrades every check downstream.

Endpoint

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

{
  "card_type": "vn.national_id",
  "image1": {
    "id": "7db00808-0416-45cf-a5cb-3b6dfbd7bb74",
    "base64": "",
    "label": "id_card.vn.national_id.front",
    "metadata": "{}"
  },
  "image2": {
    "id": "a4facba3-334b-41fb-97e3-4766cb70ae29",
    "base64": "",
    "label": "id_card.vn.national_id.back",
    "metadata": "{}"
  },
  "special_id_type": ""
}

Parameters:

Param	Type	Required	Default	Description
card_type	string	Yes	—	Type of identity card. See Usage Recommendations.
image1	ImageData	Yes	—	Image of the card's front side, or the back side when image2 is empty.
image2	ImageData	No	—	Image of the card's back side.
special_id_type	string	No	default	ID string provided by CAKE to select a special use case. Omit to use the default.

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 per image, never both.

Sample Request

curl -X POST \
  '<BASE_URL>/v1/verify_id_card_sanity_sync' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -H 'Content-Type: application/json' \
  -d '{
    "card_type": "vn.national_id",
    "image1": { "id": "7db00808-0416-45cf-a5cb-3b6dfbd7bb74" },
    "image2": { "id": "a4facba3-334b-41fb-97e3-4766cb70ae29" }
  }'

Response

{
  "data": {
    "status": "success",
    "card_sanity": {
      "score": 1,
      "verdict": "good"
    },
    "image1": {
      "id": "3ebebfe1-cf6c-4c7a-bee2-2dba834a6f1d",
      "transformed_image_id": "",
      "card_box": null
    },
    "image2": null,
    "request_id": "f77bf948-fce3-48f3-b61c-396e4cd9a89b"
  },
  "errors": []
}

Field	Type	Description
data.status	string	success or failure.
data.card_sanity.verdict	string	good, or the first issue found. See Verdict Definitions.
data.card_sanity.score	float	Range 0–1. When verdict is good the score is 1; for other verdicts a higher value means the card is more likely unqualified.
data.card_sanity.info	string	Optional extra context — for example the last 6 digits of the NID chip.
data.image1	ImageResult	Result for the first image.
data.image2	ImageResult	Result for the second image, or null when not supplied.
data.request_id	string	Request ID; quote it to CAKE Support when checking logs.

ImageResult

Field	Type	Description
id	string	ID of the analysed image.
transformed_image_id	string	ID of the transformed image, present only when the image was transformed.
card_box	CardBox	Corner coordinates of the detected card: top_left, top_right, bottom_left, bottom_right, each { "x": int, "y": int }.

Only the first issue found is returned, not a full list of defects. Show the user a generic retake message (never the verdict or score) and re-check.

Glare verdicts

Where a verdict names an alert on image1 or image2, the alert is one of blurry, dirty, too_dark, too_bright, glare, glare_safe, glare_unsafe:

Field	Type	Description
glare	string	The image has a glare spot, which could be anywhere on the image.
glare_safe	string	There is glare, but outside the regions holding essential information such as ID number, name and date of birth.
glare_unsafe	string	Glare falls inside an important region and may affect the OCR result.

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

• Verdict Definitions — what each sanity verdict means
• Read ID Card Info — extract the card fields once sanity passes