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:
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.
Run a face matching request without OzCapsula. Matching happens on the backend, so secure data transmission isn't needed.

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.

OzLiveness.open({
    session_token,                 // required for OzCapsula (Web SDK 1.9.2+)
    action: ['video_selfie_blank'],
    params: {
        extract_best_shot: true
    },
    // ... other options
});

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.

Your media file keys and the corresponding filenames must match.

Request body

{
  "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)
)

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

Add your reference photo to the folder

Add your reference photo to the folder identified by the folder_id from the response of your Liveness request: POST /api/folders/{{folder_id}}/media/.

Request body

{
  "media:tags": {
    "UUID_of_reference_photo.jpeg": ["photo_selfie"]
  }
}

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.

Request body

{
  "analyses": [
    {
      "type": "biometry",
      "source_media": [
        <original_name_with_extension>,
        <UUID_of_reference_photo.jpeg>
      ]
    }
  ]
}

The response will contain the result of the biometry analysis.

PreviousHow to Integrate Oz Liveness into Your Mobile Application NextFace Matching for Non-OzCapsula Flow

Last updated 23 days ago

Was this helpful?