Overview
eKYC Platform
Face Authentication
Vision Score
Behavioral Biometric (BehavioIQ)
SIM Verification
Mule Account Database
Overview
API Docs
eKYC Core
Demo Apps
Download SDKs
Privacy Policy
FAQ

TrustVision API Documentation v1.0.0

Mule Account Database API

The Mule Account Database API helps identify and flag accounts suspected of being used for money-mule activity. Use it to report a suspected mule account together with the identity information you have on it, and to search for a suspected mule account using identity information or a facial image.

Report Mule Account

The report mule account service allows one to report a suspected mule account with their identity information.

1. Request

Method	Path	Content-Type	Auth Required
POST	`/v1/report_mule_account`	application/json	Yes

Request Body:

JSON

{
    "image": {
        "id": string,
        "base64": string,
        "label": string,
        "metadata": json,
        "embedding": []float
    },
    "account_identifier": {
        "national_id": string,
        "identifier_type": string,
        "flag": string,
        "country": string,
        "dob": string,
        "first_name": string,
        "last_name": string,
        "middle_name": string,
        "metadata": JSON
    }
}

Where

Name	Type	Required	Description
image	JSON	No	Image of the identity card's front side.
account_identifier	JSON	Yes	Contains info about the account holder's identity.

Which each image's parameters contains:

Name	Type	Required	Description
`id`	string	No	ID of image is returned from API Upload
`base64`	string	No	base64 encoded text of image data
`label`	string	No	label of the image as described at Label table
`metadata`	string_json	No	key-value string, key should be string, value should be string, int, float, bool. Example `"{\"id\":\"123456789\",\"type\":1}"`
`embedding`	[]float	No	Vector embedding of the face in the image.

Note:

If you use id, omit base64, label, metadata, and embedding.
If you use base64, you can also include label and metadata. Omit id and embedding.
If you use embedding, omit all other image parameters.
The priority order for processing is: id, then base64, then embedding.

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.

The account_identifier object contains:

Name	Type	Required	Description
national_id	string	No	National identification number.
identifier_type	string	No	Type of the identification document.
flag	string	No	Flag to indicate the type of report: (reported, suspected, confirmed, blacklisted, convicted)
country	string	No	Country that issued the ID, in ISO 3166-1 alpha-2 format (e.g., "vn").
dob	string	No	Date of birth in YYYY-MM-DD format.
first_name	string	No	First name of the account holder.
last_name	string	No	Last name of the account holder.
middle_name	string	No	Middle name of the account holder.
metadata	JSON	No	Additional key-value data.

Note:

At least one of the following must be provided: image OR national_id in account_identifier.
In the account_identifier object, at least one field (excluding the flag field) must be provided.

Authentication mechanism is described in Authentication.

Sample Request

bash

curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/report_mule_account \
-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 \
'
{

    "account_identifier": {
        "national_id": "098765432109",
        "identifier_type": "national_id",
        "flag": 1,
        "country": "VN",
        "dob": "1995-08-15",
        "first_name": "B",
        "middle_name": "VĂN",
        "last_name": "NGUYỄN"
    },
    "image": {
        "id": "a4facba3-334b-41fb-97e3-4766cb70ae29",
    }
}
'

2. Response

The response will be a JSON with following format:

javascript

{
    "data": {
        "status": string, "success" or "failure"
        "id": string, // mule account face ID
        "message": string, "success" or "update_success" or "only_one_face_image_or_embedding"
        "metadata": JSON
    },
    "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.

error code	description
`image_too_blur`	the input image is too blur
`image_too_dark`	the input image is too dark
`image_too_bright`	the input image is too bright (glare)

In case of any other errors, the data field will be empty, and the server sends one of the following HTTP status codes with an 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

Sample Response

JSON

{
    "data": {
        "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
        "message": "success",
        "metadata": {},
        "status": "success"
    }
}

Search Mule Account

This service allows you to search for a suspected mule account using their identity information or facial image.

1. Request

Method	Path	Content-Type	Auth Required
POST	`/v1/search_mule_account`	application/json	Yes

Request Body:

JSON

{
    "image": {
        "id": string,
        "base64": string,
        "label": string,
        "metadata": json,
        "embedding": []float
    },
    "account_identifier": {
        "national_id": string,
        "identifier_type": string,
        "country": string,
        "dob": string,
        "first_name": string,
        "last_name": string,
        "middle_name": string
    }
}

Where

Name	Type	Required	Description
image	JSON	No	Image of the identity card's front side.
account_identifier	JSON	Yes	Contains info about the account holder's identity.

Which each image's parameters contains:

Name	Type	Required	Description
`id`	string	No	ID of image is returned from API Upload
`base64`	string	No	base64 encoded text of image data
`label`	string	No	label of the image as described at Label table
`metadata`	string_json	No	key-value string, key should be string, value should be string, int, float, bool. Example `"{\"id\":\"123456789\",\"type\":1}"`
`embedding`	[]float	No	Vector embedding of the face in the image.

Note:

If you use id, omit base64, label, metadata, and embedding.
If you use base64, you can also include label and metadata. Omit id and embedding.
If you use embedding, omit all other image parameters.
The priority order for processing is: id, then base64, then embedding.

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.

The account_identifier object contains:

Name	Type	Required	Description
national_id	string	No	National identification number.
identifier_type	string	No	Type of the identification document.
country	string	No	Country that issued the ID, in ISO 3166-1 alpha-2 format (e.g., "vn").
dob	string	No	Date of birth in YYYY-MM-DD format.
first_name	string	No	First name of the account holder.
last_name	string	No	Last name of the account holder.
middle_name	string	No	Middle name of the account holder.
metadata	JSON	No	Additional key-value data.

Note:

At least one of the following must be provided: image OR national_id in account_identifier.

Authentication mechanism is described in Authentication.

Sample Request

bash

curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/search_mule_account \
-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 \
'
{
    "account_identifier": {
        "national_id": "098765432109",
        "identifier_type": "national_id",
        "country": "VN",
        "dob": "1995-08-15",
        "first_name": "B",
        "middle_name": "VĂN",
        "last_name": "NGUYỄN"
    },
    "image": {
        "id": "a4facba3-334b-41fb-97e3-4766cb70ae29",
    }
}
'

2. Response

The response will be a JSON with following format:

javascript

{
    "data": {
        "status": string, // "success" or "failure"
        "verdict": string, // the highest level of flag found
        "matched": int, // number of mule account faces found
        "similar_face": int, // number of faces
        "mule_account_flags": []string // set of flags for each mule account face found
        "matched_face_counts": map[string]{matched,count} // statistics of matched faces
        "statistics_by_flag":map[string]int // statistics of matched faces by flag
    },
    "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.

error code	description
`image_too_blur`	the input image is too blur
`image_too_dark`	the input image is too dark
`image_too_bright`	the input image is too bright (glare)

In case of any other errors, the data field will be empty, and the server sends one of the following HTTP status codes with an 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

Sample Response

JSON

{
    "data": {
        "status": "success",
        "verdict": "convicted",
        "mule_account_face_count": 4,
        "face_count": 4,
        "mule_account_flags": [
            "blacklisted",
            "convicted"
        ],
        "matched_face_counts": {
            "country": {
                "matched": true,
                "count": 4
            }
        }
    }
}

.css-9x8bsw{-webkit-text-decoration:none;text-decoration:none;}.css-9x8bsw:hover{-webkit-text-decoration:underline;text-decoration:underline;}Mule Account Database API

Mule Account Database API