API Docs · eKYC Core

Common objects

Two shapes recur across the eKYC Core surface: the ImageData object every image-taking endpoint accepts, and the envelope its JSON responses are wrapped in. They are defined here once and referred to by name from each endpoint page.

The three lookup tables — Image label table, Card type table and Response errors — stay on the Overview, because they are read alongside the authentication and usage rules rather than alongside a single object.

ImageData

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.

Wherever an endpoint's Request table types a parameter ImageData — image, image1, image2, or an array of them such as selfies, images or qr1_images — this is the object it takes.

Each key is optional on its own, but the two ways of naming an image are mutually exclusive:

• 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.

A few endpoints accept one further key on the same object — an embedding, for instance. Where they do, the endpoint's own Request section carries the extra row and the note that goes with it.

Response envelope

Where an endpoint answers in JSON, the body carries two top-level keys. data holds the result, and its fields differ from endpoint to endpoint, so each endpoint page documents its own. errors carries the same three keys on every endpoint and is defined below.

{
    "data": {
        "status": string, // "success" or "failure"
        ...
    },
    "errors": [
        {
            "code": string,
            "message": string,
            "detail": {
                "field": string, // optional, which parameter is invalid.
                ... // any other information that can be useful for client
            },
        },
        ... // other errors
    ]
}

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. If the data.status is "failure", the "errors" field will tell you why it failed, with a code belonging to that endpoint — those are listed under Failure codes on the endpoint's own page.

Each entry in errors carries:

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. Response errors on the Overview lists those for the eKYC Core surface as a whole; each endpoint page carries the list documented for that endpoint under Failure codes, and the two do not match on every endpoint.

The download endpoints are the exception to the shape above. On success they send the file itself as binary content, so they use this envelope only to report an error — and then data is {}. See Download image and Download file.

All failure codes, by endpoint

Every eKYC Core endpoint documents its own Failure codes section — repeated per endpoint rather than deduplicated, because the sets genuinely differ: request_not_found_exception is documented on only 16 of the 36 endpoints below, Face OTP both drops and adds codes the rest share, and the file endpoints redefine what 413/415 mean. This table is an index over those pages, not a replacement for them — each row names every endpoint that documents a given HTTP code, error code and description exactly as its own page has it. Get result is the one endpoint of the 37 with no Failure codes section at all.

This table covers the HTTP-status transport codes only — the endpoint-specific business codes (image_has_no_faces, incorrect_card_type, and the rest of the data.status: "failure" codes a handful of endpoints define) stay on each endpoint's own Failure codes section, since they only make sense in that endpoint's context.