ID Card · Standard API · eKYC Core

Verify identity

POST/v1/verify_identity_sync

Checks an identity card against a portrait image and returns a trust verdict, optionally verifying age from the date of birth on the card.

Request

MethodPOST
Path/v1/verify_identity_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
image1ImageDataRequiredimage of the identity card's front side
image2ImageDataOptionalportrait image
age_verificationAgeVerificationOptionalage verification request, to use this feature please contact administrator to get permission

Which AgeVerification's parameter contains value:

NameTypeRequiredDescription
age_requirementfloatOptionalrequired minimum age for your business rule
  • 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,
    "image1": {
        "id": string,
        "base64": string,
        "label": string,
        "metadata": string_json,
    },
    "image2": {
        "id": string,
        "base64": string,
        "label": string,
        "metadata": string_json,
    },
    "age_verification": {
      "age_requirement": float
    }
}

Sample request

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

Response

data.verify_identity carries the verdict and its score, with optional details and score_details breakdowns per checked feature. When you send age_verification, data.age_verification returns the age calculated from the date of birth read off the card, and a verdict of good if that age meets your min_age_requirement. The data.status is either "success" or "failure" depending on whether the request has been successfully processed or not.

JSON
{
    "data": {
        "status": string, // "success" or "failure"
        "verify_identity": {
            "score": float,
            "verdict": string // "good", "age_not_match",...
            "details": [ // optional if client needs to provide
                { "verdict": string, "score": float, "name": string, "info": string },
                { "verdict": string, "score": float, "name": string, "info": string },
            ],
            "score_details": [ // optional if client needs to provide
                { "verdict": string, "score": float, "name": string, "info": string },
                { "verdict": string, "score": float, "name": string, "info": string },
            ]
        },
        "age_verification": {
            "age": float, // calculated age from date of birth
            "date_of_birth": string, // date of birth from ocr id card
            "format": string, // format of date_of_birth eg. "yyyy/MM/dd"
            "min_age_requirement": float, // age requirement for your business
            "verdict": string, // "good" if age >= or min_age_requirement, otherwise "alert"
        },
        "image1_id": string, // ID of the image
        "image2_id":string, // ID of the image2
    },
    "errors": [
        {
            "code": string,
            "message": string,
            "detail": {
                "field": string, // optional, which parameter is invalid.
                ... // any other information that can be useful for client
            },
        },
        ... // other errors
    ]
}

A verified identity comes back like this:

JSON
{
  "data": {
    "image1_id": "1956f390-0db8-4fbb-b818-284877f245fd",
    "image2_id": "41da97f1-61e2-4da0-8de4-c0734b3a4fdd",
    "status": "success",
    "verify_identity": {
      "details": null,
      "score": 1,
      "score_details": null,
      "verdict": "good"
    }
  }
}

Failure codes

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

Error codeDescriptionSupported countries
age_not_matchage of people in the id card and portrait not matchall

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.