ID Card · Standard API · eKYC Core

Read doc info

POST/v1/read_doc_info_sync

Reads the pages of a supported legal document and returns the text parsed from it, together with where the document sits inside each image.

Request

MethodPOST

Path/v1/read_doc_info_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
`doc_type`	string	Required	type of document
`images`	`List of ImageData`	Required	images of document

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.

JAVASCRIPT

{
    "doc_type": string,
    "images": [{
        "id": string,
        "base64": string,
        "label": string,
        "metadata": string_json,
    }]
}

The `doc_type` parameter

doc_type names the kind of document being read, and should be one of following values:

`doc_type`	Description	Supported countries
`vn.business_license`	Any business license in Vietnam	`vietnam`
`global.any_document`	Any document	`all`

User can specify 4 corner's coordinates of each image, these information will be send in metadata:

JSON

"doc_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 },
},

Sample request

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

doc_information carries the merged and normalized information from the OCR of all pages in the document, and each image also comes back with the corner coordinates of the document found inside it. The status is either "success" or "failure" depending on whether the request has been successfully processed or not.

JAVASCRIPT

{
    "request_id": string, // ID of the request
    "status": string, // "success" or "failure"
    "data": {
        "images": [{
            "id": string,
            "transformed_image"{ // optional, in case the image is transformed
                "id": string, // ID of the transformed image
                "folder": string, // the folder contains the transformed image file
                "storage": string, // name of the storage which stores the transformed image file
            },
            "doc_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 },
            },
            "ocr": {
                "parsed": [ // list of parsed information from OCR
                    {
                        "field": string, // uid, name, dateOfBirth, careOf, ...
                        "value": string,
                    },
                    ... // other fields
                ],
                "raw": [ // list of raw OCR text boxes
                    {
                        "text": string, // detected text
                        "bounding_box": [
                            {
                                "x": float,
                                "y": float,
                            },
                            {
                                "x": float,
                                "y": float,
                            },
                            {
                                "x": float,
                                "y": float,
                            },
                            {
                                "x": float,
                                "y": float,
                            }
                        ],
                        "label": string, // label of the box
                        "line": int,
                        "group": int,
                    },
                    ... // other text boxes
                ]
            },
        },
        // other image
        ]
        "doc_information": [ // merged and normalized information from OCR of all pages in document
            {
                "field": string, // field name ("identity_number", "full_name", "birth_date")
                "value": string, // value of the field ("123456789", "Sohit Gour", "1998-06-23")
                "confidence_verdict": string, // verdict of value ("SURE", "UNSURE", ""), empty mean Not Available. This field is shown if client enable 'enable_evaluate_confidence'
                "confidence_score": float, // confidence score of predict value. This field is shown if client enable 'enable_evaluate_confidence'
            },
            ... // other pair of card information
        ]
    },
    "errors": [
        {
            "code": string, // "unexpected_error", "image_too_dark", "image_too_bright", ...
            "message": string, // message to clarify the error code
            "detail": {
                ... // any information to help trace and debug
            }
        },
        ... // other errors
    ]
}

A read of a Vietnamese business licence comes back like this:

JSON

{
  "data": {
    "doc_information": [
      {
        "field": "doc_name",
        "value": "GIẤY CHỨNG NHẬN ABC"
      },
      {
        "field": "business_number",
        "value": "0123456789"
      },
      {
        "field": "first_registration_date",
        "value": "01/01/2001"
      },
      {
        "field": "update_date",
        "value": "01/11/2017"
      },
      {
        "field": "business_name_vi",
        "value": "CÔNG TY TNHH TRUSTING SOCIAL"
      },
      ...
    ],
    "images": [
      {
        "doc_box": {
          "bottom_left": {
            "x": 68,
            "y": 998
          },
          "bottom_right": {
            "x": 798,
            "y": 1002
          },
          "top_left": {
            "x": 88,
            "y": 27
          },
          "top_right": {
            "x": 764,
            "y": 3
          }
        },
        "id": "ae0d296b-8e39-413f-bdc5-93b53628d2d1",
        "ocr": null,
        "transformed_image_id": ""
      }
    ],
    "status": "success"
  }
}

Failure codes

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

Error code	Description	Supported countries
`image_too_blur`	the input image is too blur	`all`
`image_too_dark`	the input image is too dark	`all`
`image_too_bright`	the input image is too bright (glare)	`all`
`image_has_no_faces`	the input image has no faces	`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.
`404`	`request_not_found_exception`	The request ID is not found when polling result by id
`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.

PreviousDetect ID cards NextRead QR info

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

The doc_type parameter

Sample request

Response

Failure codes

Request

The `doc_type` parameter