Common · 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 lists the codes for the eKYC Core surface as a whole — the two lists do not match on every endpoint.