This section contains the most common cases of integrating the Oz Forensics Liveness and face Biometry system.

The scenarios can be combined together, for example, integrating liveness into both web and mobile applications or integrating liveness with face matching.

You can also download Postman collections for Oz API. Please find them here.

In this section, we listed the guides for the face matching checks.

Oz Forensics specializes in liveness and face matching: we develop products that help you identify your clients remotely and protect against spoofing and deepfake attacks. Oz software helps you to add facial recognition to your software systems and products. You can integrate Oz modules in many ways depending on your needs. We are constantly improving our components, increasing their quality.

Oz Liveness

• Oz Liveness is responsible for recognizing a living person on a video it receives. Oz Liveness can distinguish a real human from their photo, video, mask, or other kinds of spoofing and deepfake attacks. The accuracy of our algorithms is confirmed by BixeLab, the independent biometric testing laboratory.

Here are the confirmation letters from the laboratory.

PAD levels 1 and 2:

PAD level 3:

IAD:

Oz Liveness is also certified by iBeta, a NIST-accredited biometric testing laboratory, with 100% accuracy.

Our liveness technology protects against both injection and presentation attacks.

The injection attack detection is layered. Our SDK examines user environment to detect potential manipulations: browser, camera, etc. Further on, the deep neural network comes into play to defend against even the most sophisticated injection attacks.

The presentation attack detection is based on deep neural networks of various architectures, combined with a proprietary ensembling algorithm to achieve optimal performance. The networks consider multiple factors, including reflection, focus, background scene, motion patterns, etc. We offer both passive (no gestures) and active (various gestures) , ensuring that your customers enjoy the user experience while delivering accurate results for you. The iBeta test was conducted using passive Liveness, and since then, we have significantly enhanced our networks to better meet the needs of our clients.

• Oz Face Matching (Biometry) verifies that the person performing the check is the same person shown on the document. Oz Biometry looks through the video, finds the best shot where the person is clearly seen, and compares it with the photo from ID or another document. The algorithm's accuracy is 99.99% confirmed by NIST FRVT.

Our biometry technology has both 1:1 Face Verification and 1:N Face Identification, which are also based on ML algorithms. To train our neural networks, we use our own framework based on state-of-the-art technologies. Our private dataset of over 4.5 million unique faces covers a wide range of ethnic groups and attributes (predicted race, age, etc.), helping our models produce robust matching scores.

Our face detector can work with photos and videos. Also, the face detector excels in detecting faces in images of IDs and passports (which can be rotated or of low quality).

The Oz software combines accuracy in analysis with ease of integration and use. To further simplify the integration process, we have provided a detailed description of all the key concepts of our system in this section. If you're ready to get started, please refer to our , which provide the step-by-step instructions on how to achieve your facial recognition goals quickly and easily.

Oz Forensics adheres to SOC 2® and ISO/IEC 27001:2022 standards.

In this section, you will find the description of both API and SDK components of Oz Forensics Liveness and face biometric system. API is the backend component of the system, it is needed for all the system modules to interact with each other. SDK is the frontend component that is used to:

1) take videos or images which are then processed via API,

2) display results.

We provide two versions of API.

With full version, we provide you with all functionality of Oz API.

The Lite version is a simple and lightweight version with only the necessary functions included.

The SDK component consists of web SDK and mobile SDK.

Web SDK is a plugin that you can embed into your website page and the adapter for this plugin.

Mobile SDK is SDK for iOS and Android.

This article describes Oz components that can be integrated into your infrastructure in various combinations depending on your needs.

The typical integration scenarios are described in the Integration Quick Start Guides section.

Oz API

Oz API is the central component of the system. It provides RESTful application programming interface to the core functionality of Liveness and Face matching analyses, along with many important supplemental features:

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

• Authentication, roles and access management,

• Asynchronous analyses,

• Ability to work with videos as well as images.

For more information, please refer to and . To test Oz API, please check the Postman collection .

Under the logical hood, Oz API has the following components:

• File storage and database where media, analyses, and other data are stored,

• The Oz BIO module that runs neural network models to perform facial biometry magic,

• Licensing logic.

The front-end components (Oz Liveness Mobile or Web SDK) connect to Oz API to perform server-side analyses either directly or via customer's back end.

iOS and Android SDK are collectively referred to as Mobile SDKs or Native SDKs. They are written on Swift and Kotlin/Java, respectively, and designed to be integrated into your native mobile application.

Mobile SDKs implement the out-of-the-box customizable user interface for capturing Liveness video and ensure that the two main objectives are met:

• The capture process is smooth for users,

• The quality of a video is optimal for the subsequent Liveness analysis.

After Liveness video is recorded and available to your mobile application, you can run the server-side analysis. You can use corresponding SDK methods, call the API directly from your mobile application, or pass the media to your backend and interact with Oz API from there.

The basic integration option is described in the .

Mobile SDKs are also capable of On-device Liveness and Face matching when Oz API is not required.

Web Adapter and Web Plugin together constitute Web SDK.

Web SDK is designed to be integrated into your web applications and have the same main goals as Mobile SDKs:

• The capture process is smooth for users,

• The quality of a video is optimal for the subsequent Liveness analysis.

Web Adapter needs to be set up on a server side. Web Plugin is called by your web application and works in a browser context. It communicates with Web Adapter, which, in turn, communicates with Oz API.

Web SDK adds the two-layer protection against injection attacks:

1. Collects information about browser context and camera properties to detect usage of virtual cameras or other injection methods.

2. Records liveness video in a format that allows server-side neural networks to search for traces of injection attack in the video itself.

Check the for the basic integration scenario, and explore the for more details.

Web UI is a convenient user interface that allows to explore the stored API data in the easy way. It relies on API authentication and database and does not store any data on its own.

Web console has an intuitive interface, yet the user guide is available .

The "Best shot" algorithm is intended to choose the most high-quality and well-tuned frame with a face from a video record. This algorithm works as a part of the analysis, so here, we describe only the best shot part. Starting with API v6.0.1, the best shot is extracted and returned in the API response by default unless disabled for a specific purpose.

1. Initiate the analysis similar to , but make sure that extract_best_shot is set to true as shown below, or this line is omitted (for API 6.0.1 and newer):

If you want to use a webhook for response, add it to the payload at this step, as described .

2. Check and interpret results in the same way as for the pure analysis.

In API 6.0, we've implemented new analysis modes:

Liveness is checking that a person on a video is a real living person.

Biometry compares two or more faces from different media files and shows whether the faces belong to the same person or not.

Best shot is an addition to the Liveness check. The system chooses the best frame from a video and saves it as a picture for later use.

Blacklist checks whether a face on a photo or a video matches with one of the faces in the pre-created database.

The objective of the Liveness check is to verify the authenticity and physical presence of an individual in front of the camera. In the passive Liveness check, it is sufficient to capture a user's face while they look into the camera. Conversely, the active Liveness check requires the user to perform an action such as smiling, blinking, or turning their head. While passive Liveness is more user-friendly, active Liveness may be necessary in some situations to confirm that the user is aware of undergoing the Liveness check.

In our Mobile or Web SDKs, you can define what action the user is required to do. You can also combine several actions into a sequence. Actions vary in the following dimensions:

• User experience,

• File size,

• Liveness check accuracy,

• Suitability for review by a human operator or in court.

In most cases, the Selfie action is optimal, but you can choose other actions based on your specific needs. Here is a summary of available actions:

Our algorithms use tags to identify which gesture the user performed. For more information, please read the article. The detailed information on how the actions, or, in other words, gestures are called in different Oz Liveness components is .

We offer different usage models for the Oz software to meet your specific needs. You can either utilize the software as a service from one of our cloud instances or integrate it into your existing infrastructure. Regardless of the usage model you choose, all Oz modules will function equally. It’s only up to you what to pick, depending on your needs.

When to choose SaaS

With the SaaS model, you can access one of our clouds without having to install our software in your own infrastructure.

Choose SaaS when you want:

• Faster start as you don’t need to procure or allocate hardware within your company and set up a new instance.

• Zero infrastructure cost as server components are located in Oz cloud.

• Lower maintenance cost as Oz maintains and upgrades server components.

• No cross-border data transfer for the regions where Oz has cloud instances.

The on-premise model implies that all the Oz components required are installed within your infrastructure. Choose on-premise for:

• Your data not leaving your infrastructure.

• Full and detailed control over the configuration.

We also provide an opportunity of using the on-device Liveness and Face matching. This model is available in Mobile SDKs.

Consider the on-device option when:

• You can’t transmit facial images to any server due to privacy concerns

• The network conditions whereon you plan using Oz products are extremely poor.

The choice is yours to make, but we're always available to provide assistance.

To improve the overall security level or Oz products, we’ve introduced a new proprietary data exchange format that provides improved data confidentiality and integrity: OzCapsula.

How it works

A proprietary data exchange format is a container that safely stores and transmits transaction-related media data.

When you capture video using Oz SDK, your media is placed into the OzCapsula container along with all required information. The package can be processed only in Oz API due to internal mechanisms, so it is significantly more difficult to access the package containing.

Benefits

• Integrity and Authenticity Guaranteed. Each container’s content is verified by the API, ensuring data arriving from the user device is genuine, untampered, and fully intact.

• Full Confidentiality of Internal Data. Multi-layered cryptographic protection keeps all data, metadata, and technical details hidden from unauthorized viewing, extraction, or interpretation.

• Unified Data Package. All content is stored in a single, secure file, simplifying transmission and enabling consistent, predictable processing.

• Built-In Investigation Tools. Every action within the container is logged, giving complete visibility for incident analysis and rapid troubleshooting.

• Strict, Built-In Access Control. Only authorized systems can open or use the container, preventing misuse, tampering attempts, or unauthorized integration.

• Ready for High-Volume Workflows. The container is designed to scale effortlessly, supporting any number of transmissions without performance or integration issues.

Minimal component versions:

• API: 6.6.1.

• Web SDK: 1.9.10.

• Native SDKs: 10.0.0.

You will also require a new token: session_token.

1. Configure SDK and API:

The webhook feature simplifies getting analyses' results. Instead of polling after the analyses are launched, add a webhook that will call your website once the results are ready.

When you create a folder, add the webhook endpoint (resolution_endpoint) into the payload section of your request body:

{    
  "resolution_endpoint": "address.com", // use address of your website here
    ... // other request details - folder etc.
}

You'll receive a notification each time the analyses are completed for this folder. The webhook request will contain information about the folder and its corresponding analyses.

Oz Mobile SDK stands for the Software Developer’s Kit of the Oz Forensics Liveness and Face Biometric System, providing seamless integration with customers’ mobile apps for login and biometric identification.

The most common cyberattacks can be divided to three groups: injection, integration, and presentation attacks. Below, you’ll find some examples for mobile and web SDKs.

An injection attack on a liveness detection system is an attempt to bypass liveness verification mechanisms by injecting falsified data or modifying the execution logic of the frontend SDK. This type of attack is typically carried out by code injection, tampering with the runtime environment, or replacing camera input components (e.g., intercepting and substituting the video stream in real time, using virtual cameras, or manipulating JavaScript logic in the Web SDK). The goal of such attacks is to trick the liveness system into accepting fake or pre-recorded content as a genuine live interaction with the user.

Examples for mobile SDKs:

• Virtual cameras.

The Liveness detection algorithm is intended to detect a real living person in a media.

1. You're .

2. You have already marked by correct tags into this folder. For API 4.0.8 and below, please note: the Liveness analysis works with videos and shotsets, images are ignored. If you want to analyze an image, upload it as a shotset (archive) with a single image and mark with the video_selfie_blank tag.

The collection check algorithm is designed to check the presence of a person using a database of preloaded photos. A video fragment and/or a photo can be used as a source for comparison.

1. You're .

2. You have already marked by correct tags into this folder.

Oz API is the most important component of the system – it connects all the other components together, and it is the unified REST interface you call to run Liveness and Biometry analyses. Oz API:

• provides the unified REST API interface to run the Liveness and Biometry analyses,

• processes authorization and user-permission management,

• Security updates.

• Fixed the bug with the time_created and folder_id parameters of the Detect method that sometimes might have been generated incorrectly.

Download and install the Postman client from this Then download the JSON file needed:

Oz API 5.1.0 works with the same collection.

Launch the client and import Oz API collection for Postman by clicking the Import button:

Click files, locate the JSON needed, and hit Open to add it:

The collection will be imported and will appear in the Postman interface:

If you want to get back to the previous (up to 6.4.2) versions' design, reset the customization settings of the capture screen and apply the parameters that are listed below.

Please note: this feature has been implemented in 8.1.0.

To add or update the language pack for Oz Android SDK, please follow these instructions:

1. Go to the folder for the locale needed, or create a new folder. Proceed to for the details.

2. Create the file called strings.xml.

To launch one or more analyses for your media files, you need to create a folder via Oz API (or use an existing folder) and put the files into this folder. Each file should be marked by : they describe what's pictured in a media and determine the applicable analyses.

To create a folder and upload media to it, call POST /api/folders/

To add files to the existing folder, call POST /api/folders/{{folder_id}}/media/

Add the files to the request body; tags should be specified in the payload.

Here's the example of the payload for a passive Liveness video and ID front side photo.

To start using Oz iOS SDK, follow the steps below.

1. Embed Oz iOS SDK into your project as described .

2. Get a trial license for SDK on our or a production license by . We'll need your bundle id. Add the license to your project as described .

You can generate the trial license or contact us by to get a productive license. To create the license, your bundle id is required. After you get a license file, there are two ways to add the license to your project.

1. Rename this file to forensics.license and put it into the project. In this case, you don't need to set the path to the license.

2. During the runtime: when initializing SDK, use the following method.

Please note: this feature has been implemented in 8.1.0.

To add or update the language pack for Oz iOS SDK, use the set(languageBundle: Bundle) method. It shows the SDK that you are going to use the non-standard bundle. In OzLocalizationCode, use the custom language (optional).

• If you don’t set the custom language and bundle, the SDK uses the pre-installed languages only.

Download and install the Postman client from this Then download the JSON file needed:

Launch the client and import Oz API Lite collection for Postman by clicking the Import button:

Click files, locate the JSON needed, and hit Open to add it:

The collection will be imported and will appear in the Postman interface:

In this section, we explain how to use Oz Flutter SDK for iOS and Android.

Before you start, it is recommended that you install:

• Flutter 3.0.0 or newer;

• Android SDK 21 or newer;

This callback is called when the system encounters any error. It contains the error details and telemetry ID that you can use for further investigation.

Closing the plugin

To force the closing of the plugin window, use the close() method. All requests to server and callback functions (except on_close) within the current session will be aborted.

Example:

var session_id = 123;

OzLiveness.open({
  // We transfer the arbitrary meta data, by which we can later identify the session in Oz API
  meta: {
    session_id: session_id 
  },
  // After sending the data, forcibly close the plugin window and independently request the result
  on_submit: function() {
    OzLiveness.close();
    my_result_function(session_id);
  }
});

Hiding the plugin window without cancelling the callbacks

To hide the plugin window without cancelling the requests for analysis results and user callback functions, call the hide() method. Use this method, for instance, if you want to display your own upload indicator after submitting data.

An example of usage:

To connect SDK to Oz API, specify the API URL, access token, and SSL pins as shown below.

OZSDK.setApiConnection(Connection.fromServiceToken(host: "https://<link>.ozforensics.com", token: token, sslPins: pins)) { (token, error) in
}

Alternatively, you can use the login and password provided by your Oz Forensics account manager:

OZSDK.setApiConnection(Connection.fromCredentials(host: “https://<link>.ozforensics.com”, login: login, password: password, sslPins: pins)) { (token, error) in
    // Your code to handle error or token
}

By default, logs are saved along with the analyses' data. If you need to keep the logs distinct from the analysis data, set up the separate connection for telemetry as shown below:

To generate the license, we need the domain name of the website where you are going to use Oz Forensics Web SDK, for instance, your-website.com. You can also define subdomains.

Set the license as shown below:

• With license data:

OzLiveness.open({
    license: {
        'payload_b64': 'some_payload',
        'signature': 'some_data',
        'enc_public_key': 'some_key'
    },
    ...,
})

• With license path:

Check whether the license is updated properly.

Example

Proceed to your website origin and launch Liveness -> Simple selfie.

Once the license is added, the system will check its validity on launch.

For commercial use of Oz Forensics products, a license is required. The license is time-limited and defines the software access parameters based on the terms of your agreement. Some product features are also controlled by the license:

Once you initialize mobile SDK, run Web Plugin, or use Oz Bio, the system checks if your license is valid. The check runs in the background and has minimal impact on the user experience.

As you can see on the scheme above, the license is required for:

• Mobile SDKs for iOS and Android,

• Web SDK, which consists of Web Adapter and Web Plugin,

• Oz BIO, which is needed for server analyses and is installed for .

For each of the components, you require a separate license which is bound to this component. Thus, if you use all three components, three licenses are required.

To issue a license for mobile SDK, we require your bundle (application) ID. There are two types of licenses for iOS and Android SDKs: online and offline. Any license type can be applied to any analysis mode: on-device, server-based, or hybrid.

As its name suggests, an online license requires a stable connection. Once you initialize our SDK with this license, it connects to our license server and retrieves information about license parameters, including counters of transactions or devices, where:

• Transaction: increments each time you start a video capture.

• Device: increments when our SDK is installed on a new device.

The online license can be transaction-limited, device-limited, or both, according to your agreement.

The main advantages of the online license are:

• You don’t need to update your application after the license renewal,

• And if you want to add a new bundle ID to the incense, there’s also no need to re-issue it. Everything is done on the fly.

The data exchange for the online license is quick, ensuring your users won't experience almost any delay compared to using the offline license.

Please note that even though on-device analyses don’t need the Internet themselves, you still require a connection for license verification.

Offline license is a type of license that can work without Internet. All license parameters are set in the license file, and you just need to add the file to your project. This license type doesn’t have any restrictions on transactions or devices.

The main benefit of the offline license is its autonomy, allowing it to function without a network connection. However, when your license expires, and you add a new one, you’ll require to release a new version of your application in Google Play and App Store. Otherwise, the SDK won’t function.

How to add a license to mobile SDK:

Web SDK license is almost similar to the mobile SDK offline license. It can function without network connection, and the license file contains all the necessary parameters, such as expiration date. Web SDK license also has no restrictions on transactions or devices.

The license is bound to URLs of your domains and/or subdomains. To add the license to your SDK instance, you need to place it to the Web SDK container as described . In rare cases, it is also possible to .

The difference between Mobile SDK offline license and Web SDK license is that you don’t need to release a new application version when Web SDK license is renewed.

For on-premise installations, we offer a dedicated license with a limitation on activations, with each activation representing a separate Oz BIO seat. This license can be online or offline, depending on whether your Oz BIO servers have internet access. The online license is verified through our license server, while for offline licenses, we assist you in within your infrastructure and activating the license.

For test integration purposes, we provide a free trial license that is sufficient for initial use, such as testing with your datasets to check analysis accuracy. For Mobile SDKs, you can generate a one-month license yourself on our website: . If you would like to integrate with your web application, please to obtain a license, and we will also assist you in configuring your dedicated instance of our Web SDK. With the license, you will receive credentials to access our services.

Once you're ready to move to commercial use, a new production license will be issued. We’ll provide you with new production credentials and assist you with integration and configuration. Our engineers are always available to help.

Our software offers flexible licensing options to meet your specific needs. Whether you prioritize seamless updates or prefer autonomous operation, we have a solution tailored for you. If you have any questions, please contact us.

Getting an access token

To get an access token, call POST /api/authorize/auth/ with credentials (which you've got from us) containing the email and password needed in the request body. The host address should be the API address (the one you've also got from us).

{
	"credentials": {
		"email": "{{user_email}}", // your login
		"password": "{{user_password}}" // your password
	}
}

The successful response will return a pair of tokens:access_token and expire_token.

access_token is a key that grants you access to system resources. To access a resource, you need to add your access_token to the header.

headers = {‘ X-Forensic-Access-Token’: <access_token>}

access_token is time-limited, the limits depend on the account type.

• service accounts – OZ_SESSION_LONGLIVE_TTL (5 years by default),

• other accounts – OZ_SESSION_TTL (15 minutes by default).

expire_token is the token you can use to renew your access token if necessary.

If the value ofexpire_date > current date, the value of current sessionexpire_date is set to current date + time period that is defined as shown above (depending on the account type).

To renewaccess_token and expire_token, call POST /api/authorize/refresh/. Add expire_token to the request body and X-Forensic-Access-Token to the header.

In case of success, you'll receive a new pair of access_token and expire_token. The "old" pair will be deleted upon the first authentication with the renewed tokens.

The Oz API is a comprehensive Rest API that enables facial biometrics, allowing for both face matching and liveness checks. This write-up provides an overview of the essential concepts that one should keep in mind while using the Oz API.

Authentication, roles, and access management

To ensure security, every Oz API call requires an access token in its HTTP headers. To obtain this token, execute the POST /api/authorize/auth method with login and password provided by us. Pass this token in X-Forensic-Access-Token header in subsequent Oz API calls.

This article provides comprehensive details on the authentication process. Kindly refer to it for further information.

Furthermore, the Oz API offers distinct user roles, ranging from CLIENT, who can perform checks and access reports but lacks administrative rights, e.g., deleting folders, to ADMIN, who enjoys nearly unrestricted access to all system objects. For additional information, please consult .

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. A folder can contain the unlimited number of media, and each of the media can be a target of several analyses. Also, analyses can be performed on a bunch of media.

Media OZ API works with photos and videos. Video can be either a regular video container, e.g., MP4 or MOV, or a ZIP archive with a sequence of images. Oz API uses the file mime type to define whether media is an image, a video, or a shot set.

It is also important to determine the semantics of a content, e.g., if an image is a photo of a document or a selfie of a person. This is achieved by using tags. The selection of tags impacts whether specific types of analyses will recognize or ignore particular media files. The most important tags are:

• photo_id_front – for the front side of a photo ID

• photo_selfie – for a non-document reference photo

• video_selfie_blank

The full list of Oz media tags with their explanation and examples can be found .

Since video analysis may take a few seconds, the analyses are performed asynchronously. This implies that you initiate an analysis (/api/folders/{{folder_id}}/analyses/) and then monitor the outcomes by polling until processing is complete (/api/analyses/{{analysis_id}} for a single analysis or /api/folders/{{folder_id}}/analyses/ for all folder’s analyses). Alternatively, there is a webhook option available. To see an example of how to use both the polling and webhook options, please check .

These were the key concepts of Oz API. To gain a deeper understanding of its capabilities, please refer to the of our developer guide.

The Biometry algorithm is intended to compare two or more photos and detect the level of similarity of the spotted faces. As a source media, the algorithm takes photos, videos, and documents (with photos).

Requirements

1. You're authorized.

2. You have already created a folder and added your media marked by correct tags into this folder.

Processing steps

1. Initiate the analysis for the folder: POST /api/folders/{{folder_id}}/analyses/

If you want to use a webhook for response, add it to the payload at this step, as described .

You'll needanalysis_id or folder_id from response.

2. If you use a webhook, just wait for it to return the information needed. Otherwise, initiate polling:

• GET /api/analyses/{{analysis_id}} – for the analysis_id you have from the previous step.

• GET /api/folders/{{folder_id}} – for all analyses performed on media in the folder with the folder_id you have from the previous step.

Repeat until the resolution_status and resolution fields change status to any other except PROCESSING, and treat this as a result.

Check the response for the min_confidence value. It is a quantitative result of matching the people on the media uploaded.

Overview

Metadata is any optional data you might need to add to a system object. In the meta_data section, you can include any information you want, simply by providing any number of fields with their values:

…
meta_data:
{
  "field1": "value1",
  "field2": "value2"
}
…

Objects and methods

Metadata is available for most Oz system objects. Here is the list of these objects with the API methods required to add metadata. Please note: you can also add metadata to these objects during their creation.

You can also change or delete metadata. Please refer to our .

You may want to use metadata to group folders by a person or lead. For example, if you want to calculate conversion when a single lead makes several Liveness attempts, just add the person/lead identifier to the folder metadata.

Here is how to add the client ID iin to a folder object.

In the request body, add:

Another case is security: when you need to process the analyses’ result from your back end, but don’t want to perform this using the folder ID. Add an ID (transaction_id) to this folder and use this ID to search for the required information. This case is thoroughly explained .

If you store PII in metadata, make sure it complies with the relevant regulatory requirements.

You can also add metadata via SDK to process the information later using API methods. Please refer to the corresponding SDK sections:

Instant API, or non-persistent operation mode, has been introduced in API 6.0.1. It is a mode where we do not save any data anywhere. All data is being used only within a request: you send it, receive the response, and that's all, nothing gets recorded. This ensures you do not store any sensitive data, which might be crucial for GDPR compliance. Also, it significantly reduces storage requirements.

To enable this mode, when you prepare the config.py file to run the API, set the OZ_APP_COMPONENTS parameter to stateless. Call POST /api/instant/folders/ to send the request without saving any data. Authorization for Instant API should be set on your side.

If you use Instant API with Web SDK, in Web Adapter configuration, set architecture to lite. The version of Web SDK should be 1.7.14 or above.

• CPU: 16 cores, 32 threads, base frequency – 2.3 GHz, single-core maximum turbo frequency – 4 GHz.

• RAM: 32 GB, DDR 5, Dual Channel.

To evaluate your RPS and RPM and configure your system for optimal performance, please contact us.

Prior to the launch, prepare a configuration file with the parameters listed below.

These parameters are crucial to run Instant API.

You can find the Instant API methods or download the collection below.

To start using Oz Android SDK, follow the steps below.

1. Embed Oz Android SDK into your project as described here.

2. Get a trial license for SDK on our website or a production license by email. We'll need your application id. Add the license to your project as described here.

3. Connect SDK to API as described . This step is optional, as this connection is required only when you need to process data on a server.

4. Capture videos using methods described . You'll send them for analysis afterward.

5. Analyze media you've taken at the previous step. The process of checking liveness and face biometry is described .

6. If you want to customize the look-and-feel of Oz Android SDK, please refer to .

Recommended Android version: 5+ (the newer the smartphone is, the faster the analyses are).

Recommended versions of components:

We do not support emulators.

Available languages: EN, ES, HY, KK, KY, TR, PT-BR.

To obtain the sample apps source code for the Oz Liveness SDK, proceed to the GitLab repository:

Follow the link below to see a list of SDK methods and properties:

Download the demo app latest build .

When you perform an analysis, the result you get is a number. For biometry, it reflects a chance that the two or more people represented in your media are the same person. For liveness, it shows a chance of deepfake or a spoofing attack: that the person in uploaded media is not a real one. You can get these numbers via API from a JSON response.

1. Authorize.

2. Make a request to the folder or folder list to get a JSON response. Set the with_analyses parameter to true.

3. For the Biometry analysis, check the response for the min_confidence value:

This value is a quantitative result of matching the people on the media uploaded.

4. For the Liveness Analysis, seek the confidence_spoofing value related to the video you need:

This value is a chance that a person is not a real one.

To process a bunch of analysis results, you can parse the appropriate JSON response.

CocoaPods

To integrate OZLivenessSDK into an Xcode project via the CocoaPods dependency manager, add the following code to Podfile:

pod 'OZLivenessSDK', :git => 'https://gitlab.com/oz-forensics/oz-mobile-ios-sdk', :tag => 'VERSION'

Version is optional as, by default, the newest version is integrated. However, if necessary, you can find the older version number in Changelog.

Since 8.1.0, you can also use a simpler code:

// for the latest version
pod ‘OZLivenessSDK’
// OR, for the specific version
// pod ‘OZLivenessSDK’, ‘8.22.0’

By default, the full version is being installed. It contains both server-based and on-device analysis modes. To install the server-based version only, use the following code:

pod 'OZLivenessSDK/Core', :git => 'https://gitlab.com/oz-forensics/oz-mobile-ios-sdk.git',  :tag => 'VERSION'

For 8.1.0 and higher:

pod ‘OZLivenessSDK/Core’
// OR
// pod ‘OZLivenessSDK/Core’, ‘8.22.0’

SPM

Please note: installation via SPM is available for versions 8.7.0 and above.

Add the following package dependencies via SPM: (if you need a guide on adding the package dependencies, please refer to the ). OzLivenessSDK is mandatory. If you don't need the on-device analyses, skip the OzLivenessSDKOnDevice file.

You can also add the necessary frameworks to your project manually.

1. Download the SDK files from and add them to your project.

• OZLivenessSDK.xcframework,

• OZLivenessSDKResources.bundle,

• OZLivenessSDKOnDeviceResources.bundle (if you don't need the on-device analyses, skip this file).

1. Download the TensorFlow framework 2.11 from .

2. Make sure that:

• both xcframework are in Target-Build Phases -> Link Binary With Libraries and Target-General -> Frameworks, Libraries, and Embedded Context;

• the bundle file(s) are in Target-Build Phases -> Copy Bundle Resources.

Add the following URL to the build.gradle of the project:

allprojects {
  repositories {
    maven { url "https://ozforensics.jfrog.io/artifactory/main" }
  }
}

Add this to the build.gradle of the module (VERSION is the version you need to implement. Please refer to Changelog):

For the server-based version only

Please note: this is the default version.

dependencies {
  implementation 'com.ozforensics.liveness:sdk:VERSION'
}

For both server-based and on-device versions

Please note: the resulting file will be larger.

dependencies {
implementation 'com.ozforensics.liveness:full:VERSION'
}

Also, regardless of the mode chosen, add:

android {
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
}

From 8.18.0, you can move the SDK into a Google Dynamic Feature module and load it on demand. Since most of the SDK's size comes from its native .so files, moving all SDK interaction into a separate module can noticeably reduce your base app size.

To support this, the SDK exposes an onContextAttachListener callback that fires from attachBaseContext inside the SDK's Activity, so you can call SplitCompat.installActivity() when needed:

Web Plugin is a plugin called by your web application. It works in a browser context. The Web Plugin communicates with Web Adapter, which, in turn, communicates with Oz API.

Please find a sample for Oz Liveness Web SDK here. To make it work, replace <web-adapter-url> with the Web Adapter URL you've received from us.

For the samples below, replace https://<link>.ozforensics.com in index.html.

• Angular sample

• sample

• sample

• sample

Please note: for the plugin to work, your browser version should support JavaScript ES6 and be the one as follows or newer.

*Web SDK doesn't work in Internet Explorer compatibility mode due to lack of important functions.

This callback is called periodically during the analysis’ processing. It retrieves an intermediate result (unavailable for the capture mode). The result content depends on the Web Adapter result_mode configuration parameter.

Safe

When result_mode is safe, the on_result callback contains the state of the analysis only:

{
 "state": "finished"
}

Status

For the status value, the callback contains the state of the analysis, and for each of the analysis types, the name of the type, state, and resolution.

The folder value is almost similar to the status value, with the only difference: the folder_id is added.

In this case, you receive the detailed response possibly containing sensitive data. This mode is deprecated; for security reasons, we recommend using the safe mode.

Requirements

A dedicated Web Adapter in our cloud or the adapter deployed on-premise. The adapter's URL is required for adding the plugin.

Processing steps

To embed the plugin in your page, add a reference to the primary script of the plugin (plugin_liveness.php) that you received from Oz Forensics to the HTML code of the page. web-sdk-root-url is the Web Adapter link you've received from us.

<script src="https://web-sdk-root-url/plugin_liveness.php"></script>

This callback is called after the check is completed. It retrieves the analysis result (unavailable for the capture mode). The result content depends on the Web Adapter result_mode configuration parameter.

Safe

When result_mode is safe, the on_complete callback contains the state of the analysis only:

{
  "state": "finished"
}

Status

For the status value, the callback contains the state of the analysis, and for each of the analysis types, the name of the type, state, and resolution.

The folder value is almost similar to the status value, with the only difference: the folder_id is added.

In this case, you receive the detailed response possibly containing sensitive data. This mode is deprecated; for security reasons, we recommend using the safe mode.

Oz API Lite is the lightweight yet powerful version of Oz API. The Lite version is less resource-demanding, more productive, and easier to work with. The analyses are made within the API Lite image. As Oz API Lite doesn't include any additional services like statistics or data storage, this version is the one to use when you need a high performance.

Examples of methods

To check the Liveness processor, call GET /v1/face/liveness/health.

To check the Biometry processor, call GET /v1/face/pattern/health.

To perform the liveness check for an image, call POST /v1/face/liveness/detect (it takes an image as an input and displays the evaluation of spoofing attack chance in this image)

To compare two faces in two images, POST /v1/face/pattern/extract_and_compare (it takes two images as an input, derives the biometry templates from these images, and compares them).

To compare an image with a bunch of images, POST /v1/face/pattern/extract_and_compare_n.

For the full list of Oz API Lite methods, please refer to .

This article describes the main types of analyses Oz software performs.

• Liveness checks whether a person in a media is a real human.

• Face Matching examines two or more media to identify similarities between the faces depicted in them.

• Response codes 2XX indicate a successfully processed request (e.g., code 200 for retrieving data, code 201 for adding a new entity, code 204 for deletion, etc.).

• Response codes 4XX indicate that a request could not be processed correctly because of some client-side data issues (e.g., 404 when addressing a non-existing resource).

This article describes how to create a collection via API, how to add persons and photos to this collection and how to delete them and the collection itself if you no longer need it. You can do the same in , but this article covers API methods only.

Collection in Oz API is a database of facial photos that are used to compare with the face from the captured photo or video via the Collection analysis

Person represents a human in the collection. You can upload several photos for a single person.

The collection should be created within a company, so you require your company's company_id as a prerequisite.

Create a controller that will capture videos as follows:

The delegate object must implement the OZLivenessDelegate protocol:

Create a controller that will capture videos as follows:

action – a list of user’s while capturing the video.

Once video is captured, the system calls the onOZLivenessResult method:

To customize the Oz Liveness interface, use OZCustomization as shown below. For the description of customization parameters, please refer to .

You can generate the trial license or contact us by to get a productive license. To create the license, your applicationId (bundle id) is required.

To pass your license file to the SDK, call the OzLivenessSDK.init method with a list of LicenseSources. Use one of the following:

If you want to get back to the previous (up to 6.4.2) versions' design, reset the customization settings of the capture screen and apply the parameters that are listed below.

The Web Plugin works inside an iframe. The iframe must be allowed to use the camera, and every page involved must be served over HTTPS and covered by your license.

allow="camera" is mandatory, otherwise, the browser blocks camera access, and the plugin cannot start.

The add_lang(lang_id, lang_obj) method allows adding a new or customized language pack.

Parameters:

• lang_id: a string value that can be subsequently used as lang parameter for the open() method;

To set your own look-and-feel options, use the style section in the Ozliveness.open method. Here is what you can change:

• faceFrame – the color of the frame around a face:

Even though the analysis result is available to the host application via Web Plugin callbacks, it is recommended that the application back end receives it directly from Oz API. All decisions of the further process flow should be made on the back end as well. This eliminates any possibility of malicious manipulation with analysis results within the browser context.

To find your folder from the back end, you can follow these steps:

1. On the front end, add your unique identifier to the folder metadata.

Using Oz API, you can perform one of the following analyses:

• biometry,

• quality (liveness, best shot),

• (deprecated),

• .

The Biometry algorithm allows comparing several media and check if the people on them are the same person or not. As sources, you can use images, videos, and scans of documents (with photo). To perform the analysis, the algorithm requires at least two media (for details, please refer to ).

After comparison, the algorithm provides a number that represents the similarity level. The number varies from 100 to 0% (1 to 0), where:

• 100% (1) – faces are similar, media represent the same person,

• 0% (0) – faces are not similar and belong to different people

The Liveness detection (Quality) algorithm aims to check whether a person in a media is a real human acting in good faith, not a fake of any kind.

The Best Shot algorithm checks for the best shot from a video (a best-quality frame where the face is seen the most properly). It is an addition to liveness.

After checking, the analysis shows the chance of a spoofing attack in percents.

• 100% (1) – an attack is detected, the person in the video is not a real living person,

• 0% (0) – a person in the video is a real living person.

*Spoofing in biometry is a kind of scam when a person disguises as another person using both program and non-program tools like deepfake, masks, ready-made photos, or fake videos.

The Documents analysis aims to recognize the document and check if its fields are correct according to its type.

As an output, you'll get a list of document fields with recognition results for each field and a result of checking that can be:

• The documents passed the check successfully,

• The documents failed to pass the check.

Additionally, the result of Biometry check is displayed.

The Collection checking algorithm is used to determine whether the person on a photo or video is present in the database of pre-uploaded images. The person's face is being compared with the faces of known swindlers or a list of VIPs depending on your needs.

After comparison, the algorithm provides a number that represents the similarity level. The number varies from 100 to 0% (1 to 0), where:

• 100% (1) – the person in an image or video matches with someone in the collection,

• 0% (0) – the person is not found in the collection.

The details on each status are below.

This is the state when the analysis is being processed. The values of this state can be:

FAILED – the analysis failed due to some error and couldn't get finished;

FINISHED – job's done, the analysis is finished, and you can check the result.

Once the analysis is finished, you'll see one of the following results:

SUCCESS – everything went fine, the check succeeded (e.g., faces match or liveness confirmed);

OPERATOR_REQUIRED (except the Liveness analysis) – the result should be additionally checked by a human operator;

DECLINED – the check failed (e.g., faces don't match or some spoofing attack detected).

If the analysis hasn't been finished yet, the result inherits a value from analyses.state.

A folder is an entity that contains media to analyze. If the analyses have not been finished, the stage of processing media is shown in resolution_status:

INITIAL – no analyses applied;

FAILED – any of the analyses failed due to some error and couldn't get finished;

FINISHED – media in this folder are processed, the analyses are finished.

Folder result is the consolidated result of all analyses applied to media from this folder. Please note: the folder result is the result of the last-finished group of analyses. If all analyses are finished, the result will be:

SUCCESS – everything went fine, all analyses completed successfully;

OPERATOR_REQUIRED (except the Liveness analysis) – there are no analyses with the DECLINED status, but one or more analyses have been completed with the OPERATOR_REQUIRED status;

DECLINED – one or more analyses have been completed with the DECLINED status.

Here’s a step-by-step guide on how to issue a service token in Oz API 5 and 6.

curl -L 'https://{{host}}/api/authorize/auth' \
-H 'Content-Type: application/json' \
--data-raw '{
    "credentials": {
        "email": "admin_email@email.com",
        "password": "your_admin_password"
    }
}'

{
  …
    "user": {
        "user_type": "ADMIN",
  …
    },
    "access_token": "<token>",
    …
}

Master license is the offline license that allows using Mobile SDKs with any bundle_id, unlike the regular licenses. To get a master license, create a pair of keys as shown below. Email us the public key, and we will email you the master license shortly after that. Your application needs to sign its bundle_id with the private key, and the Mobile SDK checks the signature using the public key from the master license. Master licenses are time-limited.

Generating Keys

This section describes the process of creating your private and public keys.

Creating a Private Key

To create a private key, run the commands below one by one.

openssl genpkey -algorithm RSA -outform DER -out privateKey.der -pkeyopt rsa_keygen_bits:2048
# for MacOS
base64 -i privateKey.der -o privateKey.txt
# for Linux 
base64 -w 0 privateKey.der > privateKey.txt

You will get these files:

• privateKey.der is a private .der key;

• privateKey.txt is privateKey.der encoded by base64. This key containing will be used as the host app bundle_id signature.

The OpenSSL command specification:

To create a public key, run this command.

You will get the public key file: publicKey.pub. To get a license, please email us this file. We will email you the license.

SDK initialization:

Prior to the SDK initializing, create a base64-encoded signature for the host app bundle_id using the private key.

Signature creation example:

Pass the signature as the masterLicenseSignature parameter during the SDK initialization.

If the signature is invalid, the initialization continues as usual: the SDK checks the list of bundle_id included into the license, like it does it by default without a master license.

Overview and benefits

In version 6.0.1, we introduced a new feature which allows you to send all required data and receive the analysis result within a single request.

Before 6.0.1, interacting with the API required multiple requests: you had to create a folder and upload media to it, initiate analyses (see Liveness, Biometry, and Blacklist), and then either poll for results or use webhooks for notifications when the result was ready. This flow is still supported, so if you need to send separate requests, you can continue using the existing methods that are listed above.

However, the new API operation mode significantly simplifies the process by allowing you to send a single request and receive the response synchronously. The key benefits are:

• Single request for everything – all data is sent in one package, eliminating the risk of data loss.

• Synchronous response – no need for polling or webhooks to retrieve results.

• High performance – supports up to 36 analyses per minute per instance.

To use this method, call POST /api/folders/. In the X-Forensic-Access-Token header, pass your . Add media files to the request body and define the tags and metadata if needed in the payload part.

In response, you receive analysis results.

You're done.

What tags are for

To work properly, the resolution algorithms need each uploaded media to be marked with special tags. For video and images, the tags are different. They help algorithms to identify what should be in the photo or video and analyze the content.

Tags for video files

The following tag types should be specified in the system for video files.

• To identify the data type of the video:

  • video_selfie

• To identify the orientation of the video:

  • orientation_portrait – portrait orientation;

  • orientation_landscape – landscape orientation.

• To identify the action on the video:

  • video_selfie_left – head turn to the left;

  • video_selfie_right – head turn to the right;

On January 1, 2027, the One Shot gesture will become unavailable. Please plan your .

The tags listed allow the algorithms recognizing the files as suitable for the (Liveness) and analyses.

Important: in API 4.0.8 and below, to launch the Quality analysis for a photo, pack the image into a .zip archive, apply the SHOTS_SET type, and mark it with video_*. Otherwise, it will be ignored by algorithms.

Example of the correct tag set for a video file with the “blink” action:

The following tag types should be specified in the system for photo files:

• A tag for selfies:

  • photo_selfie – to identify the image type as “selfie”.

• Tags for photos/scans of ID cards:

Important: in API 4.0.8 and below, to launch the Quality analysis for a photo, pack the image into a .zip archive, apply the SHOTS_SET type, and mark it with video_*. Otherwise, it will be ignored by algorithms.

Example of the correct tag set for a “selfie” photo file:

Example of the correct tag set for a photo file with the face side of an ID card:

Example of the correct set of tags for a photo file of the back of an ID card:

Configuring Oz API

The main change in interaction with API is that you require to send data with another content type, as data container is a binary file: Content-Type = application/octet-stream. We've added support for this content type along with container functionality.

Also, Instant API now requires client’s private and public keys to function. The paths to these keys should be specified in OZ_JWT_PRIVATE_KEY_PATH and OZ_JWT_PUBLIC_KEY_PATH in the configuration file.

To generate them, use commands as listed below.

# Generate private key:
openssl ecparam -name secp384r1 -genkey -noout | openssl pkcs8 -topk8 -nocrypt -out ./jwt.key
# Generate public key:
openssl ec -in ./jwt.key -pubout -out ./jwt.pub

Configuration parameters

These parameters are mandatory for OzCapsula to work. Add them to your configuration file.

OZ_SESSION_TOKEN_LIFETIME=<your_ttl_for_session_token>
OZ_JWT_PRIVATE_KEY_PATH=<jwt_private_key_path>
OZ_JWT_PUBLIC_KEY_PATH=<jwt_public_key_path>
OZ_MALEWICZ_ANALYSIS_ENABLED=true

Examples

POST api/folders:

POST api/instant/folders:

Before you start with SDK, obtain a session token:

1. (Optional, only if you use stateful API) Authorize as any non-OPERATOR role.

2. Call GET {{host}}/api/authorize/session_token.

Example request

Example response