How to Perform a Face Matching Analysis
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.
Depending on the API configuration:
Instant API: run a Liveness analysis using OzCapsula with the best shot extraction enabled. This best shot is then used for comparison.
Full API: launch a regular Liveness analysis.
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.
Instant API
Run the Liveness Analysis with Best Shot
The best shot is a frame from the Liveness video where the face is most clearly seen. When best shot extraction is enabled, the server selects this frame during the Quality (Liveness) analysis and stores it in the same folder as the source video, so it can be reused as input for the face matching (Biometry) analysis without recapturing media.
1.1. Enable Best Shot Extraction
This section describes where to switch on the best shot extraction in each Oz SDK.
Add extract_best_shot to the params map of the AnalysisProfile whose type is QUALITY, inside CaptureRequest.analysisProfileList.
val livenessProfile = AnalysisProfile(
mediaList = listOf(
MediaRequest(
id = UUID.randomUUID().toString(),
actionMedia = OzAction.Smile
)
),
type = "QUALITY",
params = mapOf("extract_best_shot" to true)
)
val captureRequest = CaptureRequest(
analysisProfileList = listOf(livenessProfile)
)After this, run createMediaCaptureScreen(captureRequest, session_token) to get the data container and send it to analysis with addContainer(container) — exactly as in the standard OzCapsula flow.
Add extract_best_shot to the params of the AnalysisProfile whose type is .quality, inside CaptureRequest.analysisProfileList.
let livenessProfile = AnalysisProfile(
mediaList: [
MediaRequest(
id: UUID().uuidString,
actionMedia: .smile
)
],
type: .quality,
params: ["extract_best_shot": true]
)
let captureRequest = CaptureRequest(
analysisProfileList: [livenessProfile]
)After this, run createMediaCaptureScreen(request: captureRequest, session_token: token) to get the data container and send it to analysis with addContainer(container).
Add extract_best_shot to the params of the object passed to OzLiveness.open(). Unlike the mobile SDKs, this parameter sits at the top level of the launch options, not nested per analysis, and works the same way regardless of whether you use the OzCapsula data container or the legacy flow.
1.2. Obtain Media for Comparison
Instant API returns the best shot in the base64 format. In the response, you will find it in folder.analyses.results_media → output_images → image_b64. Decode the base64 best shot from the Liveness response and save it as a file (e.g., best_shot.jpeg).
Run the Face Matching Analysis
Face matching is launched directly via Oz API, without the SDK capture step.
Call POST /api/instant/folders/ with your reference photo and the best shot you've obtained from the Liveness analysis as shown in 1.2.
{
"media:tags": {
"UUID_of_reference_photo.jpeg": ["photo_selfie"],
"best_shot.jpeg": ["photo_selfie"]
},
"analyses": [
{ "type": "biometry" }
]
}The response will contain the result of the biometry analysis.
Full API
Run the Liveness Analysis
val livenessProfile = AnalysisProfile(
mediaList = listOf(
MediaRequest(
id = UUID.randomUUID().toString(),
actionMedia = OzAction.Smile
)
),
type = "QUALITY"
)
val captureRequest = CaptureRequest(
analysisProfileList = listOf(livenessProfile)
)After this, run createMediaCaptureScreen(captureRequest, session_token) to get the data container and send it to analysis with addContainer(container) — exactly as in the standard OzCapsula flow.
let livenessProfile = AnalysisProfile(
mediaList: [
MediaRequest(
id: UUID().uuidString,
actionMedia: .smile
)
],
type: .quality
)
let captureRequest = CaptureRequest(
analysisProfileList: [livenessProfile]
)After this, run createMediaCaptureScreen(request: captureRequest, session_token: token) to get the data container and send it to analysis with addContainer(container).
From the response, you need folder_id and the original name of your media file (video that has been taken) which is in folder.media → original_name.
Run the Face Matching Analysis
Call Oz API with the Folder ID
Call Oz API POST /api/folders/{{folder_id}}/analyses/ with folder_id from the response of your Liveness request (Step 1). Set biometry as the analysis type and define what media files to compare in the source_media section. Use the original name and extension of your media file from Step 1, e.g., original_name.zip or original_name.mp4.
{
"analyses": [
{
"type": "biometry",
"source_media": [
<original_name_with_extension>,
<UUID_of_reference_photo.jpeg>
]
}
]
}The response will contain the result of the biometry analysis.
Last updated
Was this helpful?
