# Centralized OkayFace

## **Overview**

The user will need to submit a selfie to test on the Centralized OkayFace API. The purpose of this API is to compare the facial image on the ID card with the Selfie taken in this API to check if the user is the same as the ID card's owner.

The API also contains an *option* to enable the OkayLive API also known as "Liveness Detection" to make sure that the selfie is taken by a real person. This will greatly increase the security level of the OkayFace API to help counter fake selfie submissions.

#### Steps:

1. The user will need to re-use the JourneyId again.
2. Place the JourneyId and the content mentioned in the [API Method](#api-method) below.
3. Users can choose either [Version 1-1](#centralized-okayface-version-1-1) or [Version 1](#centralized-okayface-version-1) to call the API. *(Recommended Version 1-1)*
4. After expanding the API method, the user can read the descriptions on each parameter and place the details accordingly following this [Example](#input-example-okayface-version-1-1).
5. This Centralized OkayFace API included the integration of [Centralized OkayLive](https://api2-ekycportal.innov8tif.com/emas-ekyc-portal/centralized-okaylive), this is why the example shown in step 4 contains the "liveness detection". It also has the option to use it separately by disabling the "liveness detection" parameter.
6. The average processing time takes about 2s to 4s.

{% hint style="info" %}
Please refer to the "[<mark style="color:orange;">Image Requirement</mark>](https://api2-ekycportal.innov8tif.com/emas-ekyc-portal/image-requirement/okayface)" section to get the best result for each API return
{% endhint %}

## API Method

### Centralized OkayFace Version 1-1 *(Recommended)*

<mark style="color:green;">`POST`</mark> `https://ekycportaldemo.innov8tif.com/api/ekyc/okayface/v1-1`

#### Headers

| Name         | Type   | Description                                                                                                                                                                                                        |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| livenessMeta | String | <p>The environment the image was taken in. Possible values are <code>IOS</code>, <code>ANDROID</code>, <code>DESKTOP</code> or <code>UNKNOWN</code> (the default).</p><p>e.g. </p><p><em>{"OS":"Desktop"}</em></p> |

#### Request Body

| Name                                           | Type    | Description                                                  |
| ---------------------------------------------- | ------- | ------------------------------------------------------------ |
| imageIdCardBase64                              | string  | Uncheck 'imageIdCard' to enable this parameter to be working |
| imageBestBase64                                | string  | Uncheck 'imageBest' to enable this parameter to be working   |
| livenessDetection                              | boolean | Set to True - return liveness score                          |
| imageIdCard <mark style="color:red;">\*</mark> | object  | Face Image from ID card                                      |
| imageBest <mark style="color:red;">\*</mark>   | object  | Selfie photo                                                 |
| journeyId<mark style="color:red;">\*</mark>    | string  | Retrieve from 'Create JourneyID' API                         |

{% tabs %}
{% tab title="200 Successfully response to the user" %}
{% code title="Response Code Block" %}

```
{
    "status": "success",
    "messageCode": "api.success",
    "imageBestLiveness": {
        "probability": 0.9999331,
        "score": 9.612308,
        "quality": 0.6691686
    },
    "request_id": "1591169623008663I8E5268153513648",
    "result_idcard": {
        "confidence": 88.0169
    }
}
```

{% endcode %}
{% endtab %}

{% tab title="400: Bad Request Failed to response to the user " %}

```javascript
{
    status: "error"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Internal Server Error" %}

```javascript
{
    status: "Internal Server Error"
}
```

{% endtab %}
{% endtabs %}

### Centralized OkayFace Version 1

<mark style="color:green;">`POST`</mark> `https://ekycportaldemo.innov8tif.com/api/ekyc/okayface`

#### Request Body

| Name                                           | Type    | Description                                                  |
| ---------------------------------------------- | ------- | ------------------------------------------------------------ |
| imageIdCardBase64                              | string  | Uncheck 'imageIdCard' to enable this parameter to be working |
| imageBestBase64                                | string  | Uncheck 'imageBest' to enable this parameter to be working   |
| livenessDetection                              | boolean | Set to True - return liveness score                          |
| imageIdCard <mark style="color:red;">\*</mark> | object  | Face Image from ID card                                      |
| imageBest <mark style="color:red;">\*</mark>   | object  | Selfie photo                                                 |
| journeyId<mark style="color:red;">\*</mark>    | string  | Retrieve from 'Create JourneyID' API                         |

{% tabs %}
{% tab title="200 Successfully responded to user" %}
{% code title="Response Code Block" %}

```
{
    "status": "success",
    "messageCode": "api.success",
    "imageBestLiveness": {
        "probability": 0.9999331,
        "score": 9.612308,
        "quality": 0.6691686
    },
    "request_id": "1591169623008663I8E5268153513648",
    "result_idcard": {
        "confidence": 88.0169
    }
}
```

{% endcode %}
{% endtab %}

{% tab title="400: Bad Request Failed to response to user" %}

```javascript
{
    "status": "error"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Internal server error" %}

```javascript
{
    status:"Internal Server Error"
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Kindly refer to the page below for the interpretation of the result.
{% endhint %}

{% content-ref url="centralized-okayface/interpretation-of-result-and-recommended-threshold" %}
[interpretation-of-result-and-recommended-threshold](https://api2-ekycportal.innov8tif.com/emas-ekyc-portal/centralized-okayface/interpretation-of-result-and-recommended-threshold)
{% endcontent-ref %}

#### API Header - LivenessMeta

| Meta Key | Meta Value                                | Required                                              |
| -------- | ----------------------------------------- | ----------------------------------------------------- |
| OS       | "IOS", "ANDROID" or "DESKTOP" or "UNKOWN" | Optional *(Suggested to include for better accuracy)* |

### Input Example (OkayFace Version 1-1)

![Input using image file](https://4019998022-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRYsITG7N76MNv67B20iW%2Fuploads%2FyLbUrZENxs3O8oZfuKqN%2FCapture.JPG?alt=media\&token=372d9336-82f8-44ec-93b3-00e4f91d466d)

![Input using base64 image string](https://4019998022-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRYsITG7N76MNv67B20iW%2Fuploads%2FBbzDLXiwLxOj9ntT5KZv%2FCapture%20\(1\).JPG?alt=media\&token=88a6e65f-9d07-4e4b-88be-66a73c2b0e33)

{% hint style="info" %}
Users can either choose to activate livenessDetection by ticking the key or deactivate the livenessDetection by un-ticking the key
{% endhint %}

#### Postman Collection

{% hint style="info" %}
Get the Postman Collection\
<https://api2-ekycportal.innov8tif.com/emas-ekyc-portal/postman-collection>
{% endhint %}