How to Check Your Media for Liveness without Oz Front End

Please note: we recommend using our products in combination with either the Oz Mobile or Web SDK, as they provide a wide range of essential security features. The integration example below is provided for reference only and should be used at your own discretion.

Oz API is a rich Rest API for facial biometry, where you can do liveness checks and face matching. Oz API features are:

• Persistence: your media and analysis are stored for future reference unless you explicitly delete it,

• Ability to work with videos as well as images,

• Asynchronous analyses,

• Authentication,

• Roles and access management.

The unit of work in Oz API is a folder: you can upload interrelated media to a folder, run analyses on them, and check for the aggregated result.

This step-by-step guide describes how to perform a liveness check on a facial image or video that you already have with Oz backend: create a folder, upload your media to this folder, initiate liveness check and poll for the results.

For better accuracy and user experience, we recommend that you use our Web and/or Native SDK on your front end for face capturing. Please refer to the relevant guides:

• Integration of Oz Liveness Web SDK,
• Integration of Oz Liveness Mobile SDK.

Before you begin, make sure you have Oz API credentials. When using SaaS API, you get them from us:

Login: [e-mail] Password: … API: https://sandbox.ohio.ozforensics.com Web Console: https://sandbox.ohio.ozforensics.com

For the on-premise Oz API, you need to create a user yourself or ask your team that manages the API. See the guide on user creation via Web Console. Consider the proper user role (CLIENT in most cases or CLIENT ADMIN, if you are going to make SDK work with the pre-created folders from other API users). In the end, you need to obtain a similar set of credentials as you would get for the SaaS scenario.

You can explore all API methods with Oz Postman collection.

1. Get the access token

For security reasons, we recommend obtaining the access token instead of using the credentials. Call POST /api/authorize/auth with your login and password in the request body.

{
    "credentials": {
        "email": "<login>", // your admin access email
        "password": "<password>" // the password you’ve got from us
     }
}

Obtain access_token from the response and add it to the X-Forensic-Access-Token of all subsequence requests.

2. Convert a single image to an archive (for API 4.0.8 and below)

Omit this step for API 5.0.0 and above.

With API 4.0.8 and below, Oz API requires video or archived sequence of images in order to perform liveness check. If you want to analyze a single image, you need to transform it into a ZIP archive. Oz API will treat this archive as a video.

Make sure that you use corresponding video-related tags later on.

3. Upload media to a folder

To create a folder and upload your media into it, call POST /api/folders/, adding the media you need to the body part of the request.

In the payload field, set the appropriate tags:

{
    "media:tags": {
        "video1": [
            "video_selfie",
            "video_selfie_blank",
            "orientation_portrait"
        ],
    }
}

The successful response will return code 201 and folder_id you’ll need later on.

4. Initiate the analysis

To launch the analysis, call POST /api/folders/{{folder_id}}/analyses/ with folder_id from the previous step. In the request body, specify the liveness check to be launched.

{
    "analyses": [
        {
            "type": "quality"
        }
    ]
}

The results will be available in a short while. The method will return analysis_id that you’ll need at the next step.

5. Poll for the results

Repeat calling GET /api/analyses/{{analysis_id}} with the analysis_id from the previous step once a second until the state changes from PROCESSING to something else. For a finished analysis:

• get the qualitative result from resolution (SUCCESS or DECLINED).

• get the quantitative results from results_media[0].results_data.confidence_spoofing. confidence_spoofing ranges from 0.0 (real person) to 1.0 (spoofing).

Here is the Postman collection for this guide.

6KB

Oz API Check with No Front End.postman_collection.json

With these steps completed, you are done with Liveness check via Oz API. You will be able to access your media and analysis results in Web UI via browser or programmatically via API.

Oz API methods can be combined with great flexibility. Explore Oz API using the API Developer Guide.