# Overview

The Progeny RESTful API `https://be.progeny.tech/api/v3`uses the HTTP POST and GET methods to create and update resources in our database.

{% hint style="warning" %}
The request body must be encoded as multipart/form-data.
{% endhint %}

{% hint style="info" %}
All API methods return JSON response.
{% endhint %}

## Making API calls and getting a response

To get a response from each of our endpoints you will first need to make a POST request to obtain a task Id.  You then pass in the Id when forming your GET request to get a response.

We'll look at an example using the /liveness endpoint.

## Get a task Id

<mark style="color:green;">`POST`</mark> `https://be.progeny.tech/api/v3/services/face_liveness/`

#### Request Body

| Name                                    | Type    | Description                                                                   |
| --------------------------------------- | ------- | ----------------------------------------------------------------------------- |
| image<mark style="color:red;">\*</mark> | String  | The file path to an image of the user's face in PNG, JPEG, or JPG file format |
| extend\_data                            | Boolean | Set to true to retrieve extended data in the liveness response                |

{% tabs %}
{% tab title="200: OK A task Id" %}

```javascript
{
    "id": "98008e56-cd6f-410c-9d8d-f9e620661395"
}
```

{% endtab %}
{% endtabs %}

The next step is to pass in that Id into your GET request.

## Perform a liveness check

<mark style="color:blue;">`GET`</mark> `https://be.progeny.tech/api/v3/services/task/?id={{task_id}}`

#### Path Parameters

| Name                                 | Type   | Description                                |
| ------------------------------------ | ------ | ------------------------------------------ |
| id<mark style="color:red;">\*</mark> | String | The Id you obtained from your POST request |

{% tabs %}
{% tab title="200: OK The result of the liveness check" %}

```javascript
{
    "id": 2158,
    "status": "SUCCESS",
    "result": {
        "data": {
            "liveness": {
                "data": {
                    "error": "Failed to detect face",
                    "error_code": "FACE_NOT_FOUND"
                },
                "result": false
            },
            "issues": {
                "liveness": {
                    "FACE_NOT_FOUND": "Failed to detect face"
                }
            }
        },
        "status": 200
    }
}
```

{% endtab %}
{% endtabs %}

## A quick word about images

Please be aware that our algorithm requires the submitted picture to simulate real-life scenarios.  When testing but also in providing guidance to your end-users, please bear in mind the following points:

* Images should be taken with a device under real-life lightning conditions and without filters
* Avoid using artificially generated selfies, filtered, or enhanced images
* Similarly, avoid using images where the subject is wearing sunglasses, has long or bushy facial hair that sticks out a lot in front of the face, or has a significantly distorted face
* Images taken under bad light conditions, with high motion blur, or excessive light will not provide the most accurate results<br>

Furthermore, images included in each API request must conform to the following requirements:

* PNG, JPEG, or JPG file format and as uncompressed as possible.  Do not go below 70%
* Between 480x480 and 4096x4096 pixels.  **For the best results, we recommend a maximum height of 1080px**
* No larger than 2MB
* Face size should be no lower than 224 pixels
* The minimum resolution between the subject's eyes should be no lower than 85 pixels
* Orientation:
  * Face pitch (equivalent to looking up and down) should be between -25 to 25 degrees
  * Yaw angle (equivalent to looking left and right) should be between -25 to 25 degrees
  * Face roll angle (equivalent to tilting left and right) from -35 to 35 degrees

## Endpoints - Quick View

| Endpoint                      | Description                                                                                                                                                                                                                                                                                                            |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| /accounts/token/obtain        | authenticate and obtain an access token                                                                                                                                                                                                                                                                                |
| /accounts/token/refresh       | <p>Can be used to obtain new token without the need to send username/password again <br><br>See: <a href="https://www.oauth.com/oauth2-servers/making-authenticated-requests/refreshing-an-access-token/"><https://www.oauth.com/oauth2-servers/making-authenticated-requests/refreshing-an-access-token/></a>    </p> |
| /services/register\_face/     | Register an image of a person's face with selected provider to be used later for Authentication                                                                                                                                                                                                                        |
| /services/authenticate\_face/ | Given an image of a person's face and an ID (provided by register\_face API), it determine whether the registered face match the provided image or not                                                                                                                                                                 |
| /services/liveness/           | Perform a standalone liveness check against an image                                                                                                                                                                                                                                                                   |
| /services/ocr\_card/          | Detect and extract text from a card (ID, Driver License, ..)                                                                                                                                                                                                                                                           |
| /services/ocr\_passport/      | Same as ocr\_card but for reading passports                                                                                                                                                                                                                                                                            |
| /services/kyc\_card/          | A combination ocr\_card, liveness APIs plus comparing ID/Drive License picture against the one provided in the request                                                                                                                                                                                                 |
| /services/kyc\_passport       | Same as kyc\_card but for passports                                                                                                                                                                                                                                                                                    |