# 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
`POST` `https://be.progeny.tech/api/v3/services/face_liveness/`
#### Request Body
| Name | Type | Description |
| --------------------------------------- | ------- | ----------------------------------------------------------------------------- |
| image\* | 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
`GET` `https://be.progeny.tech/api/v3/services/task/?id={{task_id}}`
#### Path Parameters
| Name | Type | Description |
| ------------------------------------ | ------ | ------------------------------------------ |
| id\* | 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
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 | Can be used to obtain new token without the need to send username/password again
See:
|
| /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 |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.progeny.tech/our-api/overview.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.