Detect ID Cards

Locates every ID card inside an image and returns its corner coordinates and card label. Use it to confirm a card is present and correctly framed before running OCR or tampering checks.

Endpoint

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

{
  "card_type": "vn.national_id",
  "image": {
    "id": "a4facba3-334b-41fb-97e3-4766cb70ae29",
    "base64": "",
    "label": "id_card.vn.national_id.front",
    "metadata": "{}"
  }
}

Parameters:

Param	Type	Required	Default	Description
card_type	string	Yes	—	Type of identity card. See Usage Recommendations.
image	ImageData	Yes	—	Image of the identity card's front side.

ImageData

interface ImageData {
  id?: string;
  base64?: string;
  label?: string;
  metadata?: string; // JSON string
}

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. If you use base64, also send label and metadata and omit id. If you use id, omit the other three.

Sample Request

curl -X POST \
  '<BASE_URL>/v1/detect_id_cards_sync' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -H 'Content-Type: application/json' \
  -d '{
    "card_type": "vn.national_id",
    "image": {
      "id": "a4facba3-334b-41fb-97e3-4766cb70ae29"
    }
  }'

Response

{
  "data": {
    "request_id": "f77bf948-fce3-48f3-b61c-396e4cd9a89b",
    "status": "success",
    "image": {
      "id": "854322f0-eb49-4bd6-b870-050fcc088d10",
      "cards": [
        {
          "card_box": {
            "top_left": { "x": 90.52290163561702, "y": 110.761657032324 },
            "top_right": { "x": 981.4022462964058, "y": 101.39770825190935 },
            "bottom_left": { "x": 102.62150720786303, "y": 679.5154545297846 },
            "bottom_right": { "x": 996.863339483738, "y": 661.6368409626185 }
          },
          "card_label": "vn.cccd_new.front",
          "transformed_image_id": ""
        }
      ]
    }
  },
  "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.image.id	string	ID of the analysed image.
data.image.cards	array	One entry per card detected in the image.
data.image.cards[].card_label	string	Detected card label, e.g. vn.cccd_new.front.
data.image.cards[].transformed_image_id	string	ID of the deskewed/cropped card image. Present only when the tenant setting enable_create_image is true.
data.image.cards[].card_box	CardBox	Corner coordinates of the detected card.

CardBox

Field	Type	Description
top_left	Point	Top-left corner, { "x": float, "y": float }.
top_right	Point	Top-right corner.
bottom_left	Point	Bottom-left corner.
bottom_right	Point	Bottom-right corner.

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.
request_not_found_exception	The request ID is not found when polling result by id.
rate_limit_exception	The number of requests exceeded your throughput limit.
internal_server_error	Some unexpected error occurs while processing the request.

Next Steps

• Verify ID Card Sanity — quality gate covering blur, glare, photocopies and multi-card images
• Read ID Card Info — extract the card fields