Liveness

POST

  https://api.apptenticate.com/api/v3/biometrics/liveness/

Authentication

Use your JWT obtained from the authentication: /docs/auth/token process to make requests to this endpoint.

The response will be 401 unauthorized if the JWT is expired. In this case, you will need to obtain a new JWT.

---

This endpoint is the entry point for all requests to the Liveness service, which allows you to process selfies and classify them as spoofing or real.

Spoofing: Attack on a facial biometric system that uses an image to deceive the authentication process.

Request data

The following parameters can be sent in the body of a request to this endpoint:

Name	Type	Description	Requerido
selfie	file	Image of the person's selfie. The endpoint supports any valid image format (PNG, JPG, JPEG, etc.).	true
return_id	boolean	Boolean indicating whether you want to get the transaction ID.	false
device	string	Device from which the liveness test is being performed. DESKTOP, IOS or ANDROID.	false
details	boolean	Boolean indicating whether you want to get liveness test details.	false

Request parameters

If you choose to display the details along with the response, you will get the following data:

Response format: JSON

data: {
    "api_response": {
        "score": 2.656599,
        "quality": 0.8511556,
        "liveness": 0.9344166
    },
}

score: The higher the score, the higher the liveness of the image. The value is not limited and can be used for calibration purposes.

quality: Defines how "appropriate" the image is for liveness checking. The value can be in the range [0,1]. Images with quality values below 0.5 will be automatically rejected by the service.

liveness: Defines how "real" the image is or if it is spoofing. The value can be in the range [0,1]. Images with liveness values below 0.5 will be automatically rejected by the service.

Example of request

Shell

Request

curl --location 'https://api.apptenticate.com/api/v3/biometrics/liveness/' \
--form 'selfie="<selfie>"' \
--form 'return_id="<return_id>"' \
--form 'device="<device>"' \
--form 'details="<details>"'

Node

Instalación

npm install axios form-data

Request

import axios from 'axios'
import FormData from 'form-data'

async function makeRequest() {
  let data = new FormData()
  let selfieStream = fs.createReadStream('<path_to_selfie_file>')

  data.append('selfie', selfieStream)
  data.append('return_id', '<return_id>')
  data.append('device', '<device>')
  data.append('details', '<details>')

  try {
    const { data } = await axios.post(
      'https://api.apptenticate.com/api/v3/biometrics/liveness/',
      data,
      {
        headers: data.getHeaders(),
        maxBodyLength: Infinity
      }
    )
    return JSON.stringify(data)
  } catch (error) {
    console.log(error)
  }
}

makeRequest()

Python

Instalación

python -m pip install requests

Request

import requests

url = "https://api.apptenticate.com/api/v3/biometrics/liveness/"

data = {
    "return_id": "<return_id>",
    "device": "<device>",
    "details": "<details>"
}

file = {"selfie": open("<path_to_selfie_file>", "rb")}  # Reemplace <path_to_selfie_file> con la ruta al archivo de selfie

response = requests.post(url, data=data, files=file)

if response.status_code == 200:
    print(response.json())
else:
    print(f"Request failed with status code {response.status_code}")

Response example

This will be the format of the response obtained when sending all the parameters:

Response format: JSON

data: {
    "valid": true,
    "api_response": {
        "score": 2.656599,
        "quality": 0.8511556,
        "liveness": 0.9344166
    },
    "id": 1111
}

When you stop sending the return_id parameter in the request, the response format will be as follows:

Response format: JSON

data: {
    "valid": true,
    "api_response": {
        "score": 2.656599,
        "quality": 0.8511556,
        "liveness": 0.9344166
    }
}

If the details parameter is also omitted in the request, the response format will be as follows:

Response format: JSON

data: {
    "valid": true
}

If the service detects any problem in the sent image, the response format will be as follows:

Response format: JSON

data: {
    "valid": false,
    "message": "Rostro muy reducido en pixeles",
    "error_code": 706
}

Rejection codes

If the request is not successful, a rejection code will be sent in the response. Possible rejection codes are:

Code	Message
700	Face to close.
701	Face to close to borders.
702	Incomplete face.
703	Obstructed face.
704	Face not detected.
705	Too many faces.
706	Face reduced in pixels
707	Incorrect angle of the face.
708	Error reading image.
709	Error processing image.
710	Error predicting face borders.
711	Internal liveness error
712	Unkown error.
713	Livenes image quality not acceptable.
714	Minimum image conditions for liveness not met.
715	Minimum score for liveness not met.