NAV
javascript

Introduction

Welcome to the JoyID – eKYC Experience a joyful identification solution.

Identity document verification

Determine whether the ID document (National ID, Passport, Driver lisence) is authentic or manipulated

Fraud Detection

Manipulated ID detection, blur and glare detection, expired ID detection, spoofing detection

Character recognition

Extract and digitalize information form ID with 98% accuracy

Liveness detection

Determines in 2 seconds whether the user’s selfie is a live human or a fake representation from photo, video, spoofing

Facial comparision

Determine whether the selfie photo taken matchs the photo on ID (in 10 year discrepancy)

JOYID Session

API Workflow

JOYID Session

Register

Request a token key for JOYID Session

var settings = {
  "url": "https://joyid.tpssoft.ai/api/token/register",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Accept": "application/json"
  },
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

The above command returns JSON structured like this:

{
    "key": "061c7022407d73328585fe04a30090ddb98c63a9"
}

Register a token key for JOYID Session.

HTTP Request

POST https://joyid.tpssoft.ai/api/token/register

Parameter Value
Accept application/json

Upload image

Upload images for JOYID Session process

var form = new FormData();
form.append("type", "first_doc");
form.append("file", fileInput.files[0], "first_doc.jpeg");

var settings = {
  "url": "https://joyid.tpssoft.ai/api/kyc/session/upload",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Accept": "application/json",
    "Authorization": "Bearer 061c7022407d73328585fe04a30090ddb98c63a9"
  },
  "processData": false,
  "mimeType": "multipart/form-data",
  "contentType": false,
  "data": form
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

The above command returns JSON structured like this:

{
    "code": "200"
}

Upload images to server for KYC processing

HTTP Request

POST https://joyid.tpssoft.ai/api/kyc/session/upload

Header

Parameter Type Description
Accept String application/json
Authorization String TOKEN

Formdata

Parameter Type Description
type String "first_doc", "second_doc" (optional), "face"
file File Image file. Maximum file size is 10MB

Process

Process JOYID Session

var form = new FormData();
var settings = {
  "url": "https://joyid.tpssoft.ai/api/kyc/session/process",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Accept": "application/json",
    "Authorization": "Bearer 061c7022407d73328585fe04a30090ddb98c63a9"
  },
  "processData": false,
  "mimeType": "multipart/form-data",
  "contentType": false,
  "data": form
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

The above command returns JSON structured like this:

{
    "code": 200,
    "data": {
        "face_matching": {
            "result": true,
            "percent": 83
        },
        "document": {
            "type": "CMND",
            "valid": true,
            "data": {
                "first": {
                    "id_num": "123456789",
                    "name": "NGUYỄN THANH TÂM",
                    "other_name": null,
                    "dob": "25/12/1990",
                    "sex": null,
                    "home_town": "Hồ Chí Minh",
                    "address": "10 Phổ Quang, Phường 2, Quận Tân Bình, TP Hồ Chí Minh",
                    "address_nlp": {
                        "level_3": "Hồ Chí Minh",
                        "level_2": "Tân Bình",
                        "level_1": "Phường 2",
                        "level_0": "10 Phổ Quang"
                    },
                    "expired_date": null
                },
                "second": {
                    "ethnic": "KINH",
                    "identity_characteristic": "sẹo thắng d0, 5cm c0, 5cm dưới đuôi mày trái",
                    "received_date": "20-07-2013",
                    "provider": null
                }
            }
        }
    }
}

Process the JOYID Session to extract the data from documents

HTTP Request

POST https://joyid.tpssoft.ai/api/kyc/session/process

Header

Parameter Type Description
Accept String application/json
Authorization String TOKEN

Customer verification

JoyID®can be flexibly applied into multiple purposes of identification

Trained with dataset of 6 millionsVietnamese ID documents and faces, JoyID® is able to detect ID fraud in manipulating ID or facial spoofing.

Liveness Detection of JoyID® enable precise facial verification to log in with 99.98% accuracy, making it more secure than password, faceID or even OTP.

Contact us for your Merchant account.

API Workflow

JOYID Verifycation

Inspect customer

Upload images for customer detection

var form = new FormData();
form.append("save", "TRUE");
form.append("image_1", fileInput.files[0], "image_1.jpg");
form.append("image_2", fileInput.files[1], "image_2.jpg");
form.append("image_3", fileInput.files[2], "image_3.jpg");
form.append("image_4", fileInput.files[3], "image_4.png");
form.append("image_5", fileInput.files[4], "image_5.jpg");

var settings = {
  "url": "https://joyid.tpssoft.ai/api/customers/inspect",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "MERCHANT-CODE": "SAMPLE_MERCHANT_CODE",
    "Accept": "application/json"
  },
  "processData": false,
  "mimeType": "multipart/form-data",
  "contentType": false,
  "data": form
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

The above command returns JSON structured like this:

{
    "code": 200,
    "data": {
        "customer_id": 16,
        "info": {
            "doc_type": null,
            "name": null,
            "other_name": null,
            "id_number": null,
            "home_town": null,
            "dob": "",
            "sex": null,
            "ethnic": null,
            "expired_date": "",
            "issued_date": "",
            "issued_by": null,
            "other": ""
        },
        "address": {
            "raw": null,
            "level_3": null,
            "level_2": null,
            "level_1": null,
            "level_0": null
        }
    }
}

Identify your customer by face images (5 images).

HTTP Request

POST https://joyid.tpssoft.ai/api/customers/inspect

Header

Parameter Type Description
Accept String application/json
MERCHANT-CODE String Merchant code provided by JOYID

Formdata

Parameter Type Description
save String "TRUE" or "FALSE"
image_1 File Image file of customer's face. Maximum file size is 2MB
image_2 File Image file of customer's face. Maximum file size is 2MB
image_3 File Image file of customer's face. Maximum file size is 2MB
image_4 File Image file of customer's face. Maximum file size is 2MB
image_5 File Image file of customer's face. Maximum file size is 2MB

Store customer

Save your customer data

var form = new FormData();
form.append("doc_type", "your_value");
form.append("name", "your_value");
form.append("other_name", "your_value");
form.append("id_number", "your_value");
form.append("home_town", "your_value");
form.append("dob", "your_value");
form.append("sex", "your_value");
form.append("ethnic", "your_value");
form.append("expired_date", "your_value");
form.append("issued_date", "your_value");
form.append("issued_by", "your_value");
form.append("other", "your_value");
form.append("address_raw", "your_value");
form.append("address_level_3", "your_value");
form.append("address_level_2", "your_value");
form.append("address_level_1", "your_value");
form.append("address_level_0", "your_value");

var settings = {
  "url": "https://joyid.tpssoft.ai/api/customers/16/save",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "MERCHANT-CODE": "SAMPLE_MERCHANT_CODE",
    "Accept": "application/json"
  },
  "processData": false,
  "mimeType": "multipart/form-data",
  "contentType": false,
  "data": form
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

The above command returns JSON structured like this:

{
    "code": 200,
}

Save your customer data

HTTP Request

POST https://joyid.tpssoft.ai/api/customers/{ID}/save

Header

Parameter Type Description
Accept String application/json
MERCHANT-CODE String Merchant code provided by JOYID

Formdata

Parameter Type Description
doc_type String Doc type
name String Name
other_name String Other name
id_number String ID Number of customer's document
home_town String Home town
dob String Date of birth
sex Integer 0: Male, 1: Female
ethnic String Ethnic is "Kinh", etc...
expired_date String Document's expired date
issued_date String Document's issued date
issued_by String Document's issued by
address_raw String Full address string
address_level_3 String City
address_level_2 String District
address_level_1 String Ward
address_level_0 String Street and the rest
other String A string field for other notes

Get your customers

Get all your customer

var form = new FormData();

var settings = {
  "url": "https://joyid.tpssoft.ai/api/customers",
  "method": "GET",
  "timeout": 0,
  "headers": {
    "MERCHANT-CODE": "SAMPLE_MERCHANT_CODE",
    "Accept": "application/json"
  },
  "processData": false,
  "mimeType": "multipart/form-data",
  "contentType": false,
  "data": form
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

The above command returns JSON structured like this:

[
  {
    "customer_id": 15,
    "info": {
        "doc_type": null,
        "name": null,
        "other_name": null,
        "id_number": null,
        "home_town": null,
        "dob": "",
        "sex": null,
        "ethnic": null,
        "expired_date": "",
        "issued_date": "",
        "issued_by": null,
        "other": ""
    },
    "address": {
        "raw": null,
        "level_3": null,
        "level_2": null,
        "level_1": null,
        "level_0": null
    }
  },
  {
    "customer_id": 16,
    "info": {
        "doc_type": null,
        "name": null,
        "other_name": null,
        "id_number": null,
        "home_town": null,
        "dob": "",
        "sex": null,
        "ethnic": null,
        "expired_date": "",
        "issued_date": "",
        "issued_by": null,
        "other": ""
    },
    "address": {
        "raw": null,
        "level_3": null,
        "level_2": null,
        "level_1": null,
        "level_0": null
    }
  },

]

Get all your customer with pagination

HTTP Request

GET https://joyid.tpssoft.ai/api/customers

Header

Parameter Type Description
Accept String application/json
MERCHANT-CODE String Merchant code provided by JOYID

Params

Parameter Type Description
limit Integer Customer per page
page Integer Page index of request

Errors

The JOYID API uses the following error codes:

Error Code Meaning
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
406 Not Acceptable
429 Too Many Requests
500 Internal Server Error
501 Service Maintenance
503 Service Unavailable