Mule Account Database

Search for an account

POST/v1/search_mule_account

Searches the reported mule accounts using identity information or a facial image, and returns the highest flag level found together with the match counts.

Request

MethodPOST
Path/v1/search_mule_account
Content-Typeapplication/json
Auth requiredYes — HMAC signing
NameTypeRequiredDescription
imageimageOptionalImage of the identity card's front side.
account_identifieraccount_identifierRequiredContains info about the account holder's identity.

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

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

Sample request

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

Response

data.verdict carries the highest level of flag found. data.status is either "success" or "failure" depending on whether the request has been successfully processed, and when processing has finished the HTTP status code is 200 — so a 200 on its own only means the search ran. The errors array alongside data is the same on both endpoints — see Errors.

JSON
{
    "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
        ]
}

A search that found four mule account faces, the most severe of them convicted:

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

Failure codes

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

Error codeDescription
image_too_blurthe input image is too blur
image_too_darkthe input image is too dark
image_too_brightthe input image is too bright (glare)

In case of any other errors, the data field will be empty, and the server sends an HTTP status code with an error code instead.

Transport, auth and rate-limit errors are the same on both calls — see Common objects & errors.