ID Card · Standard API · eKYC Core

Detect ID card tampering

POST/v1/detect_id_card_tampering_sync

Checks one or two ID card images for physical or digital tampering and returns a verdict per feature checked, plus a final verdict.

Request

MethodPOST

Path/v1/detect_id_card_tampering_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.

Name	Type	Required	Description
`image`	string	Required	image of the identity card's front side. Do not use back side for this param
`image2`	string	Optional	image of the identity card's back side
`qr1_images`	`List of ImageData`	Optional	images of the QR code on the card's front side
`qr2_images`	`List of ImageData`	Optional	images of the QR code on the card's back side
`card_type`	string	Optional	type of identity card, described at Card type table .Default is `vn.national_id`
`level`	string	Optional	specify deeply level to check tamper. Default is fully check
`videos`	`[]video`	Optional	array of video recording when detect id card tampering on SDK.
`qr1_videos`	`[]video`	Optional	array of video recording QR code when capture ID Chip frontside on SDK.
`special_id_type`	string	Optional	id string (provided by admin) to identify special use-case. Omit this param to use the default.

level values please contact the administrator.

Which each video's parameters contains:

Name	Type	Required	Description
`id`	string	Optional	ID of video is returned from API Upload
`metadata`	string_json	Optional	key-value string, key should be string, value should be string, int, float, bool. Example `"{\"id\":\"123456789\",\"type\":1}"`
`frames`	`[]FrameData`	Optional	list of video frames to be uploaded

Which FrameData's parameters contains:

Name	Type	Required	Description
`base64`	string	Optional	base64 encoded text of image data
`label`	string	Optional	label of the image as described at Label table
`index`	int	Optional	the index of this frame in the video

For image, 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.
For video, if you use id (result id is returned from Upload Image API), omit parameter frames, metadata. If you use frames, metadata, omit parameter id.

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

JSON

{
    "image": {
        "id": string,
        "base64": string,
        "label": string,
        "metadata": string_json,
    },
        "image2": {
        "id": string,
        "base64": string,
        "label": string,
        "metadata": string_json,
    },
    "qr1_images": [{
        "id": string,
        "base64": string,
        "label": string,
        "metadata": string_json,
    }],
    "qr2_images": [{
        "id": string,
        "base64": string,
        "label": string,
        "metadata": string_json,
    },
    "card_type": string,
    "level": string,
    "special_id_type": string,
    "videos": [
        {
            "id": string,
            "metadata": string_json,
            "frames": [
                {
                    "base64": string,
                    "label": string,
                    "index": int,
                },
                {
                    "base64": string,
                    "label": string,
                    "index": int,
                },
                // other frames
            ],
        },
        {
            "id": string,
            "metadata": string_json,
            "frames": [
                {
                    "base64": string,
                    "label": string,
                    "index": int,
                },
                {
                    "base64": string,
                    "label": string,
                    "index": int,
                },
                // other frames
            ],
        }
    ],
    "qr1_videos": [
        {
            "id": string,
            "metadata": string_json,
            "frames": [
                {
                    "base64": string,
                    "label": string,
                    "index": int,
                },
                {
                    "base64": string,
                    "label": string,
                    "index": int,
                },
                // other frames
            ],
        },
        {
            "id": string,
            "metadata": string_json,
            "frames": [
                {
                    "base64": string,
                    "label": string,
                    "index": int,
                },
                {
                    "base64": string,
                    "label": string,
                    "index": int,
                },
                // other frames
            ],
        }
    ],
}

Sample request

curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/detect_id_card_tampering_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": "7db00808-0416-45cf-a5cb-3b6dfbd7bb74"
    },
    "image2": {
        "id": "a4facba3-334b-41fb-97e3-4766cb70ae29"
    }
}
'

data.card_tampering carries the final verdict and its score, and details lists the verdict and score of each feature that was checked. In case the request processing has been finished, the HTTP status code will be 200, and the data.status is either "success" or "failure" depending on whether the request has been successfully processed or not.

Javascript

{
    "data": {
        "status": string, // "success" or "failure"
        "card_tampering":
        {
            "score": float,
            "verdict": string // final verdict. Reference to the verdict values table.
            "details":[ // list of results for each checked feature.
                {
                    "verdict": string, // verdict result on this checked feature. Reference to the verdict values table.
                    "score": float,
                    "info": string, // optional, information returned with this feature. Available with tax_name_unmatched verdict.
                },
                ... // other
            ]
        },
        "image_id": string, // ID of the image
        "image2_id":string, // ID of the image2
        "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
    ]
}

Verdict table: Please contact the administrator.

A card that comes back with one alert looks like this:

JSON

{
  "data": {
    "card_tampering": {
      "details": [
        {
          "name": "alert_1",
          "score": 1,
          "verdict": "card_expired"
        }
      ],
      "score": 1,
      "verdict": "alert"
    },
    "image2_id": "185aed08-53c7-433d-8dcd-e99f5131230f",
    "image_id": "4ba8de0e-9758-43fb-ac65-6f32ad3392d1",
    "status": "success"
  }
}

Failure codes

If the data.status is "failure", the "errors" field will tell you why it failed.

Error code	Description	Supported countries
`nocard_or_multicard_image`	the input image is no card	`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.
`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.

PreviousVerify ID card NextDetect ID cards

.css-9x8bsw{-webkit-text-decoration:none;text-decoration:none;}.css-9x8bsw:hover{-webkit-text-decoration:underline;text-decoration:underline;}Request

Sample request

Response

Failure codes

Request