Version: 3.0.1

Liveness Plus

POST

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

Authentication

Use your JWT obtained from the authentication process to make requests to this endpoint.

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

This endpoint is the entry point for all requests directed to the Liveness service, which allows processing selfies and classifying them as spoofing or real.

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

Request data

To make a request to this endpoint, the following parameters can be sent in its body:

Name	Type	Description	Contents
encrypted_file	binary	Encrypted packet with the metadata of the image it captures.	True
details	boolean	Boolean indicating whether to obtain test-of-life details.	False
return_id	boolean	Boolean that indicates whether you want to obtain the transaction ID.	False

Response parameters

If you choose to display the details next to the response, the following data will be obtained:

Response format: JSON
{
    "api_response": {
        "face_liveness": {
            "probability": 0.9859461
        },
        "capture_liveness": {
            "score": 1.1050358,
            "probability": 1.0
        }
    }
}

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

capture_liveness [probability]: Defines whether the capture liveness probability is 0 (attack) to 1 (live). Images with values 0 will be automatically rejected by the service.

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

Request Example and Capture Library

The capture library controls the client capture process and makes the encrypted_file object available for the call to the liveness-plus service. The server decompresses the packet to detect injection and presentation attacks.

There are 3 types of capture libraries:

Web capture library *Android capture library
iOS capture library

Note: Consult the technical team for examples focused on the following technologies, Vue, React, HTML, Angular.

1 - How to use the web capture library

General installation and configuration steps.

Install the package idlive-face-capture-web.tgz. Must be provided by Darien Technology.
- npm i idlive-face-capture-web file:./idlive-face-capture-web.tgz
Import the component.
- import 'idlive-face-capture-web';
Get the component.
- const idliveFaceCapture = document.querySelector('idlive-face-capture');

Request example

Biometrics Service Panama
Apptenticate Biometrics Service
Liveness-plus

Use the capture event to get an encrypted file and photo for verification after capture.

idliveFaceCapture.addEventListener('capture', (event) => {
    const { photo, encryptedFile } = event.detail[0];
    sendEncryptedFileToServer(photo, encryptedFile)
});

Implement the sendEncryptedFileToServer method to interact with the server.

const sendEncryptedFileToServer = (photo, encryptedFile) => {

    const serverUrl = 'https://api.apptenticate.com';
    
    const formData = new FormData();          
    formData.append('selfie', photo,'selfie.jpeg' );
    formData.append('encrypted_file', encryptedFile);
    formData.append('return_id', true);
    formData.append('citizen_id', '7-708-214');
    formData.append('device', 'DESKTOP');


    return fetch(`${serverUrl}/api/v3/biometrics/nationals/`, {
        method: "post",
        headers: {
            'Authorization': `Bearer ${token}`
        },
        body: formData
    })
    .then(response => response.json())
    .then(result => console.log(result))
    .catch(e => { console.error(e) })
    .finally();
}

Use the capture event to get an encrypted file and photo for verification after capture.

idliveFaceCapture.addEventListener('capture', (event) => {
    const { photo, encryptedFile } = event.detail[0];
    sendEncryptedFileToServer(photo, encryptedFile)
});

Implement the sendEncryptedFileToServer method to interact with the server.

const sendEncryptedFileToServer = (photo, encryptedFile) => {

    const serverUrl = 'https://api.apptenticate.com';

    const formData = new FormData();
    formData.append('frontside', blob, 'frontside.jpeg');
    formData.append('selfie', photo, 'selfie.jpeg');            
    formData.append('encrypted_file', encryptedFile);
    formData.append('return_id', true);
    formData.append('document_type', 'identification_card');


    return fetch(`${serverUrl}/api/v3/biometrics/foreigns/`, {
        method: "post",
        headers: {
            'Authorization': `Bearer ${token}`
        },
        body: formData
    })
    .then(response => response.json())
    .then(result => console.log(result))
    .catch(e => { console.error(e) })
    .finally();
}

Use the capture event to get an encrypted file for verification after capturing the photo.

idliveFaceCapture.addEventListener('capture', (event) => {
    const { encryptedFile } = event.detail[0];
    sendEncryptedFileToServer(encryptedFile) 
});

Implement a sendEncryptedFileToServer method to interact with the server.

const sendEncryptedFileToServer = (encryptedFile) => {

    const serverUrl = 'https://api.apptenticate.com';

    const formData = new FormData();
    formData.append('encrypted_file', encryptedFile);
    
    return fetch(`${serverUrl}/api/v3/biometrics/liveness/`, {
        method: "post",
        headers: {
            'Authorization': `Bearer ${token}`
        },
        body: formData
    })
    .then(response => response.json())
    .then(result => console.log(result))
    .catch(e => { console.error(e) })
    .finally();
}

Example responses

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

{
    "valid": true,
    "api_response": {
        "face_liveness": {
            "probability": 0.9859461
        },
        "capture_liveness": {
            "score": 1.1050358,
            "probability": 1.0
        }
    },
    "id": 284
}

By stopping sending the return_id parameter in the request, the response format will be as follows:

{
    "valid": true,
    "api_response": {
        "face_liveness": {
            "probability": 0.9859461
        },
        "capture_liveness": {
            "score": 1.1050358,
            "probability": 1.0
        }
    }
}

If the details parameter is additionally omitted from the request, the response format will be as follows:

{
    "valid": true
}

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

{
    "valid": false,
    "error_code": 715,
    "message": "Attack detected in the sent image.",
    "error_details": {
        "capture_liveness": "For a positive result you must get 1, value achieved: 0.0.",
        "api_response": {
            "face_liveness": {
                "probability": 0.9607433
            },
            "capture_liveness": {
                "score": 1.0851271,
                "probability": 0.0
            }
        }
    },
    "id": 287
}

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 too close.
`701`	Face too close to the edges.
`702`	Incomplete face.
`703`	Obstructed face.
`704`	Face not detected
`705`	Too many faces.
`706`	Face very reduced in pixels
`707`	Incorrect face angle.
`708`	Error reading image.
`709`	Error processing image.
`710`	Error when predicting face edges.
`711`	Life Test Engine Internal Error
`712`	Unknown error.
`713`	Image quality for life test not acceptable.
`714`	Minimum image conditions for proof of life not met.
`715`	Attack detected in the sent image.

Liveness Plus

Authentication​

Request data​

Response parameters​

Request Example and Capture Library​

1 - How to use the web capture library​

General installation and configuration steps.​

Request example​

Example responses​

Rejection codes​