ID Card · Standard API · eKYC Core

Detect ID cards

POST/v1/detect_id_cards_sync

Finds the identity cards in an image and returns each card's label and the coordinates of its four corners.

Request

MethodPOST
Path/v1/detect_id_cards_sync
Content-Typeapplication/json
Auth requiredYes — HMAC signing

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.

NameTypeRequiredDescription
card_typestringRequiredtype of identity card, described at Card type table
imageImageDataRequiredimage of the identity card's front side
  • If you use base64, label and metadata, omit parameter id.
  • If you use id (result id is returned from Upload Image API), omit parameter base64, label and metadata.

The ImageData shape — id, base64, label and metadata — is defined once on Common objects.

JSON
{
    "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.

JSON
{
    "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_labelDescription
vn.cmnd_old.frontThe front side of Vietnam national ID old version (Chứng minh nhân dân cũ)
vn.cmnd_old.backThe back side of Vietnam national ID old version (Chứng minh nhân dân cũ)
vn.cmnd_new.frontThe front side of Vietnam national ID new version (Chứng minh nhân dân mới)
vn.cmnd_new.backThe back side of Vietnam national ID new version (Chứng minh nhân dân mới)
vn.cccd.frontThe front side of Vietnam national ID latest version (Căn cước công dân)
vn.cccd.backThe back side of Vietnam national ID latest version (Căn cước công dân)
vn.cccd_new.frontThe front side of Vietnam national ID latest version (Căn cước công dân gắn chip)
vn.cccd_new.backThe back side of Vietnam national ID latest version (Căn cước công dân gắn chip)
vn.passport.frontMain page of Vietnam passport
vn.passport_new.frontMain page of Vietnam passport ne
vn.mid.frontFront side of Vietnam military ID card
vn.mid.backBack side of Vietnam military ID card
in.aadhaar.frontFront side of India Aadhaar card
in.aadhaar.backBack side of India Aadhaar card
in.aadhaar_letter.backBack side of India Aadhaar letter
in.voter.frontFront side of India Voter card
in.voter.backBack side of India Voter card
in.pan.frontFront side of India PAN card
in.pan.backBack side of India PAN card
in.passport.backBack side of India passport
in.dl.frontFront side of India driving license
ph.ump.frontThe front side of Philippines UMP
ph.tin.frontThe front side of Philippines TIN
ph.dl.frontThe front side of Philippines DL
ph.sss.frontThe front side of Philippines SSS
ph.nid.frontThe front side of Philippines NID
ph.passport.frontThe front side of Philippines passport
ph.postal.frontThe front side of Philippines postal
ph.philhealth.frontThe front side of Philippines philhealth
ph.prc.frontThe front side of Philippines PRC
ph.loyalty.frontThe front side of Philippines loyalty
mx.national_idAny of the Mexico national ID versions
mx.ine_type_eInstituto Nacional Electoral type e Card
mx.ine_type_fInstituto Nacional Electoral type f card
mx.ine_type_gInstituto Nacional Electoral type g card
mx.ine_type_hInstituto Nacional Electoral type h card

One Vietnamese chip ID card detected in the image comes back like this:

JSON
{
  "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 codeError codeDescription
401access_denied_exceptionYou are not authorized to perform the action.
400invalid_parameter_exceptionInput parameter violates a constraint.
400request_time_too_skewedThe X-TV-Timestamp header is expired, need a newer one.
404image_not_found_exceptionThe image ID is not found in DB.
404request_not_found_exceptionThe request ID is not found when polling result by id
408request_timeout_exceptionRequest takes too long to process
429rate_limit_exceptionThe number of requests exceeded your throughput limit.
500internal_server_errorSome 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.