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.

tip

If the Apptenticate Biometry or SIB Biometry, services are active, you can make a single request to the biometry endpoints for both services, optimizing requests.

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

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();
}

Apptenticate Biometrics Service

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();
}

Liveness-plus

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.