Common · Standard API · eKYC Core

Get client settings

GET/v1/client_settings

Returns your client's country, supported card types and SDK settings, optionally customized per flow or per calling device.

Request

MethodGET
Path/v1/client_settings
Content-Typeapplication/json
Auth requiredYes — HMAC signing

With following parameters:

NameTypeRequiredDescription
flow_idstringOptionalcustomize SDK setting based on your business

To get settings to depend on a specific device/version, you should add these headers

HeaderTypeRequiredDescription
X-TV-Device-ModelstringOptionalSpecify device model
X-TV-SDK-VersionstringOptionalSpecify SDK version from TrustingSocial
X-TV-OS-PlatformstringOptionalSpecify OS platform as Android | iOS | Web
X-TV-OS-VersionstringOptionalSpecify OS version

Sample request

curl -X GET \
https://tv-staging.trustingsocial.com/api/v1/client_settings
-H 'Authorization: TV <YOUR ACCESS KEY>:<CREATED SIGNATURE>' \
-H 'X-TV-Timestamp: 2019-04-21T18:00:15+07:00' \
-H 'Content-Type: application/json'

Response

In case of success, the HTTP status code will be 200.

JSON
{
    "data": {
        "country": string, // client's country: "in", "vn", "id"
        "card_types": [
            {
                "code": string, // "in.aadhaar"
                "name": string, // "Aadhaar card",
                "orientation": string, // "horizontal", "vertical"
                "has_back_side": bool, // true, false
                "front_qr": {
                    "exist": bool, // true, false
                    "type": string, // "qr_code", "bar_code"
                    "width_height_ratio": float, // width/height, example 1.0, 2.5
                },
                "back_qr": {
                    "exist": bool, // true, false
                    "type": string, // "qr_code", "bar_code"
                    "width_height_ratio": float, // width/height, example 1.0, 2.5
                },
                "front_mrz": {
                    "exist": bool, // true, false
                    "type": string, // "mrz_code"
                    "width_height_ratio": float, // width/height, example 1.0, 2.5
                },
                "back_mrz": {
                    "exist": bool, // true, false
                    "type": string, // "mrz_code"
                    "width_height_ratio": float, // width/height, example 1.0, 2.5
                },
            },
            ... // other supported card types of client's country
        ],
        "settings": {
            "scan_qr": string, // "none", "separate_step", "with_card",
            "web_app_crop_face": string // only for webapp 'no', 'auto', 'hybrid'
            "web_ui": {
                "show_score": bool // true, false: show/hide score of each result
            }
            // no means web app does not need to crop face
            // auto means web app automatically crop face
            // hybrid means web app show UI with suggestion to let customer crop face
            "liveness_modes": []string,
            "zoom_issue_devices":[]string, // define list devices have issue with zoom image. "*" means apply solution for all devices
            // Else specify list devices need to apply new solution ["Motorola Moto E (4) Plus","Xiaomi Redmi Note 5 Pro"]
            // liveness modes could be these value
            // passive - enable passive liveness on mobile
            // active - enable active liveness on mobile
            "selfie_enable_detect_multiple_face": bool, // true, false
            "enable_compare_faces": bool,
            "enable_verify_face_liveness": bool,
            "enable_read_id_card_info": bool,
            "enable_verify_portrait_sanity": bool, // true, false
            "enable_verify_id_card_sanity": bool, // true, false
            "enable_detect_id_cards": bool, // true, false
            // true mean client automatically detect multiple face when capture selfie image
            "selfie_camera_options": []string,
            "enable_encryption": bool, // true, false
            "support_transaction": bool, // true, false
            ... // other settings
        },
    },
    "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 Vietnam client with one configured card type comes back like this:

JSON
{
    "data": {
        "card_types": [
            {
                "code": "vn.national_id",
                "name": "CMND cũ / CMND mới / CCCD / Hộ chiếu",
                "orientation": "horizontal",
                "has_back_side": true,
                "front_qr": {
                    "exist": false
                },
                "back_qr": {
                    "exist": false
                }
            }
        ],
        "country": "vn",
        "settings": {
            "enable_compare_faces": true,
            "enable_convert_pdf": true,
            "enable_detect_id_card_tampering": true,
            "enable_encryption": false,
            "enable_face_retrieval": true,
            "enable_index_faces": true,
            "enable_read_id_card_info": true,
            "enable_verify_face_liveness": true,
            "enable_verify_id_card_sanity": true,
            "enable_verify_portrait_sanity": true,
            "liveness_modes": [
                "active",
                "passive"
            ],
            "scan_qr": "none",
            "selfie_camera_options": [
                "front"
            ],
            "selfie_enable_detect_multiple_face": true,
            "support_transaction": false,
            "utilities": {
                "length_video_sec": 5,
                "num_of_photo_taken": 3,
                "photo_res": "640x640",
                "timing_take_photo_sec": "1,2.5,4"
            },
            "web_app_crop_face": "none",
            "web_ui": {
                "index_collections": [
                    {
                        "id": "id_card",
                        "label": "Mặt trước CMND/CCCD/Passport"
                    },
                    {
                        "id": "portrait",
                        "label": "Hình ảnh selfie của khách hàng"
                    }
                ],
                "show_score": false
            }
        }
    }
}

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