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

Requirements

1. You're authorized.

2. You have already created a folder and added your media 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.

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 need analysis_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}}/analyses/ – for all analyses performed on media in the folder with the folder_id you have from the previous step.

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

Action shot is a frame from a video where the user performs a gesture, e.g., closed eyes for blinking. A separate frame is saved for each gesture.

Requirements

• API – 5.3.1,

• Web SDK – 1.6.15,

• Web UI – 1.3.4,

• Mobile SDK (iOS, Android, Flutter) – 8.14.

In the , set extract_action_shot to True.

Add the extract_action_shot parameter with the true value to params (iOS) / analysisParams (Android) of the Analysis structure when running the analysis.

• In the API response (API 6.6.1 and newer): analyses[].results_media[].output_images[]. Action shot has original_name = ResultImageActionShot.jpeg.

• In the report: a frame for each gesture. Generate the report via Web UI (the PDF button in the order) or API (POST /api/folders/{{folder_id}}/reports/).

Please find the Flutter repository here.

Installation and licensing

Add the lines below to pubspec.yaml of the project you want to add the plugin to.

For 8.22 or newer:

ozsdk: ^10.0.0

For 8.21 and below:

  ozsdk:
    git:
      url: https://gitlab.com/oz-forensics/oz-mobile-flutter-plugin.git
      ref: '8.8.2'

Add the license file (e.g., license.json or forensics.license) to the Flutter application/assets folder. In pubspec.yaml, specify the Flutter asset:

assets
  - assets/license.json // please note that the license file name must match to the one placed in assets

For Android, add the Oz repository to /android/build.gradle, allprojects → repositories section:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url ‘https://ozforensics.jfrog.io/artifactory/main’ } // repository URL
    }
}

For Flutter 8.24.0 or newer or Android Gradle plugin 8.0.0 or newer, add to android/gradle.properties:

android.nonTransitiveRClass=false

The minimum Android SDK (API Level) version should be 24 or higher:

defaultConfig {
  ...
  minSDKVersion 24
  ...
}

For iOS, set the minimum platform to 13 or higher in the Runner → Info → Deployment target → iOS Deployment Target.

In ios/Podfile, comment the use_frameworks! line (#use_frameworks!).

Initialize SDK by calling the init plugin method. Note that the license file name and path should match the ones specified in pubspec.yaml (e.g., assets/license.json).

Use the API credentials (login, password, and API URL) that you’ve received from us.

In production, instead of hard-coding the login and password inside the application, it is recommended to get the access token on your backend via the API auth method, then pass it to your application:

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 as shown below:

or

To start recording, use the startLiveness method to obtain the recorded media:

Please note: for versions 8.11 and below, the method name is executeLiveness, and it returns the recorded media.

To obtain the media result, subscribe to livenessResult as shown below:

To run the analyses, execute the code below.

Create the Analysis object:

Execute the formed analysis:

If you need to run an analysis for a particular folder, pass its ID:

The analysisResult list of objects contains the result of the analysis.

If you want to use media captured by another SDK, the code should look like this:

The whole code block will look like this:

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.

3. The URL to the best shot is located in the analyses.results_media -> output_images -> original_url

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.

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.

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.

on_error { 
    "code": "error_code", 
    "event_session_id": "id_of_telemetry_session_with_error", 
    "message": "<error decription>", 
    "context": {}  // additional information if any
}

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 (API Level) 24 or newer;

• dart 2.18.6 or newer;

• iOS platform 13 or newer;

• Xcode.

Please find the Flutter repository .

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.

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

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

You will get these files:

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.

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.

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 .

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.

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

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.

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: 7.0+ (API Level 24).

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 .

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. However, you can set up S3 storage to save the Instant API artifacts.

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.

Requirements

• 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.

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 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.

Quick start

<iframe src="https://your-domain.example/liveness-page" allow="camera"></iframe>

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

Requirements

The plugin reads the address of every parent window to check it against your license. When the parent page is on a different origin, the browser blocks that read and the check cannot complete. This setup is supported, but it needs an additional setting on the Web Adapter side – contact Oz representative.

iframe_allowed is no longer used. iframe support is always on, and the requirements above are all that is needed, so just remove the parameter from the Web Adapter configuration file.

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

Oz API Postman collections

6.6.5

This collection is identical to 6.0.0, plus a method introduced in 6.6.5.

6.0

5.3 and 5.2

5.0

Oz API 5.1.0 works with the same collection.

How to import a Postman collection:

Launch the client and import Oz API collection for Postman by clicking the Use resources or 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:

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.

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.

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

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.

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

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

Since 8.1.0, you can also use a simpler code:

The following code also works:

For 8.1.0 and higher:

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. Skip the OzLivenessSDKOnDevice file.

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

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

OzCapsula (SDK v8.22 and newer)

Send the encrypted container to your own backend as raw bytes (application/octet-stream). Your backend forwards it to Oz API and returns the analysis response.

func handleContainer(_ container: DataContainer) {
    YourBackend.uploadOzContainer(
        container,
        contentType: "application/octet-stream"
    ) { result in
        DispatchQueue.main.async {
            self.handleAnalysisResult(result)
        }
    }
}

Your backend submits the container to Oz API in a single synchronous POST request as shown here.

SDK 8.21 and older

To check liveness and face biometry, you need to upload media to our system and then analyze them.

Below, you'll see the example of performing a check and its description.

let analysisRequest = AnalysisRequestBuilder()
// create one or more analyses
let analysis = Analysis.init(
	media: mediaToAnalyze, // mediaToAnalyze is an array of OzMedia that were captured or otherwise created
	type: .quality, // check the analysis types in iOS methods
	mode: .serverBased)
analysisRequest.uploadMedia(mediaToAnalyze)
analysisRequest.addAnalysis(analysis)
// initiate the analyses
analysisRequest.run(
	statusHandler: { state in }, // scenario steps progress handler
	errorHandler: { _ in }  
) { result in
    // receive and handle analyses results here 
}

To delete media files after the checks are finished, use the cleanTempDirectory method.

Adding metadata

To add metadata to a folder, use AnalysisRequest.addFolderMeta.

In the params field of the Analysis structure, you can pass any additional parameters (key + value), for instance, to extract the best shot on the server side.

To use a media file that is captured with another SDK (not Oz iOS SDK), specify the path to it in the OzMedia structure (the bestShotURL property):

If you want to add your media to the existing folder, use the addFolderId method:

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:

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.

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.

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.

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.

OzCapsula (SDK v8.22 and newer)

Create a controller that will capture videos as follows:

getSessionToken() { sessionToken in
            DispatchQueue.main.async {
                do {
                    let action:OZVerificationMovement = .selfie
                    let mediaRequest = MediaRequest.action(action)
                    let profile = AnalysisProfile(mediaList: [mediaRequest],
                                                  type: .quality,
                                                  params: [:] )
                    let request = CaptureRequest(analysisProfileList: [profile], cameraPosition: .front)
                    let ozLivenessVC = try OZSDK.createMediaCaptureScreen(self, request, sessionToken: sessionToken)
                    self.present(ozLivenessVC, animated: true)
                } catch let error {
                    print(error.localizedDescription)
                }
            }
        }

The delegate object must implement the OZLivenessDelegate protocol:

extension ViewController: LivenessDelegate {
    func onResult(container: DataContainer) {
    }
    func onError(status: OZVerificationStatus?) {
    }
}

SDK 8.21 and older

Create a controller that will capture videos as follows:

let actions: [OZVerificationMovement] = [.selfie]
let ozLivenessVC: UIViewController = OZSDK.createVerificationVCWithDelegate(self, actions: actions)
self.present(ozLivenessVC, animated: true)

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

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

extension viewController: OZLivenessDelegate {
 func onError(status: OZVerificationStatus?) {
        // show error
   }
 }
 func onOZLivenessResult(results: [OZMedia]) {
   // proceed to the checks step
 }
}

The method returns the results of video capturing: the [OZMedia] objects. The system uses these objects to perform checks.

If a user closes the capturing screen manually, the failedBecauseUserCancelled error appears.

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.

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;

• lang_obj: an object that includes identifiers of translation strings as keys and translation strings themselves as values.

A list of language identifiers:

An example of usage:

OzLiveness.add_lang('en', enTranslation), where enTranslation is a JSON object.

To set the SDK language, when you launch the plugin, specify the language identifier in lang:

You can check which locales are installed in Web SDK: use the ozLiveness.get_langs() method. If you have added a locale manually, it will also be shown.

A list of all language identifiers:

The keys oz_action_*_go refer to the appropriate gestures. oz_tutorial_camera_* – to the hints on how to enable camera in different browsers. Others refer to the hints for any gesture, info messages, or errors.

Since 1.5.0, if your language pack doesn't include a key, the message for this key will be shown in English.

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:

ISO ISO/IEC 19795-2: 2007:

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.

This guide describes how to match a liveness video with a reference photo of a person that is already stored in your database.

However, if you prefer to include a photo ID capture step to your liveness process instead of using a stored photo, then you can refer to in this section.

By this time you should have already implemented liveness video recording and liveness check. If not, please refer to these guides:

In this scenario, you upload your reference image to the same folder where you have a liveness video, initiate the BIOMETRY analysis, and poll for the results.

Given that you already have the liveness video recorded and uploaded, you will be working with the same Oz API folder where your liveness video is. Obtain the folder ID as described below, and pass it to your back end.

Send the encrypted container to your own backend as raw bytes (application/octet-stream). Your backend forwards it to Oz API and returns the analysis response.

Your backend submits the container to Oz API in a single synchronous POST request as shown .

To check liveness and face biometry, you need to upload media to our system and then analyze them.

Here’s an example of performing a check:

To delete media files after the checks are finished, use the clearActionVideos

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.

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

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

You will get these files:

• 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).

• Response codes 5XX indicate that an internal server-side error occurred during the request processing (e.g., when database is temporarily unavailable).

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.

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:

Retrieve the analysis response and process it on the back end

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.

OzLiveness.open({
  ...
  meta: { 
  // the user or lead ID from an external lead generator 
  // that you can pass to keep track of multiple attempts made by the same user
    'end_user_id': '<user_or_lead_id>',
  // the unique attempt ID
    'transaction_id': '<unique_transaction_id>'
  }
});

You can add your own key-value pairs to attach user document numbers, phone numbers, or any other textual information. However, ensure that tracking personally identifiable information (PII) complies with relevant regulatory requirements.

/api/folders/?meta_data=transaction_id==unique_id1&with_analyses=true

1. Use the on_complete callback of the plugin to be notified when the analysis is done. Once used, call your back end and pass the transaction_id value.

2. On the back end side, find the folder by the identifier you've specified using the Oz API Folder LIST method:

   To speed up the processing of your request, we recommend adding the time filter as well:

3. In the response, find the analysis results and folder_id for future reference.

Web Adapter may send analysis results to the Web Plugin with various levels of verbosity. It is recommended that, in production, the level of verbosity is set to minimum. In the Web Adapter file, set the result_mode parameter to "safe".

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

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.

{
 "state": "finished",
 "analyses": {
   "quality": {
     "state": "finished",
     "resolution": "SUCCESS"
   }
 }
}

Folder

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.

1.2.5 – June 29, 2026

• Security updates.

1.2.3 – Nov. 21, 2024

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

• Security updates.

1.2.2 – Oct. 17, 2024

• Updated models.

• The file size for the detect Liveness method is now capped at 15 MB, with a maximum of 10 files per request.

• Updated the gesture list for best_shot analysis: it now supports head turns (left and right), tilts (up and down), smiling, and blinking.

• Introduced the new that can process videos and archives as well.

• Added the .

• API Lite now accepts base64.

• Improved the biometric model.

• Added the 1:N mode.

• Added the CORS policy.

• Published the documentation.

• Improved error messages – made them more detailed.

• Simplified the Liveness/Detect methods.

• Reworked and improved the core.

• Added anti-spoofing algorithms.

• Added the extract_and_compare method.

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.

Analyses in Oz system can be applied in two ways:

• manually, for instance, when you choose the Liveness scenario in our demo application;

• automatically, when you don’t choose anything and just assign all possible analyses (via API or SDK).

The automatic assignment means that Oz system decides itself what analyses to apply to media files based on its and type. If you upload files via the web console, you select the tags needed; if you take photo or video via Web SDK, the SDK picks the tags automatically. As for the media type, it can be IMAGE

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.

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.

To connect SDK to Oz API, specify the API URL, , and as shown below.

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

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

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. .

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

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

This article covers the use case when you need to perform face matching with an external photo while using OzCapsula for data transmission. Here is what you need to do.

1. Depending on the API configuration:

   1. Instant API: run a Liveness analysis using OzCapsula with the best shot extraction enabled. This best shot is then used for comparison.

   2. Full API: launch a regular Liveness analysis.

2. Run a face matching request without OzCapsula. Matching happens on the backend, so secure data transmission isn't needed.

These parameters are mandatory for OzCapsula to work. Define them in your API configuration file.

The instructions below show how to adjust the flow for each API configuration.

This guide describes the steps needed to add face matching to your liveness check.

By this time you should have already implemented liveness video recording and liveness check. If not, please refer to these guides:

How to Integrate Oz Liveness into Your Web Application

How to Integrate Oz Liveness into Your Mobile Application

Adding photo ID capture step to Web SDK

Simply add photo_id_front to the list of actions for the plugin, e.g.,

OzLiveness.open({
  session_token,
  lang: 'en',
  action: [
    'photo_id_front', 
    'video_selfie_blank'
  ],
  ...
});