> For the complete documentation index, see [llms.txt](https://doc.ozforensics.com/oz-knowledge/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.ozforensics.com/oz-knowledge/general/integration-quick-start-guides/how-to-perform-a-face-matching-analysis.md).

# 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](https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/api/oz-api/ozcapsula-data-container.md) for data transmission.&#x20;

{% hint style="info" %}
The described flow requires Oz API 6.9.0 or later. For earlier versions, please refer to [Face Matching in API 6.8.0 and Below](https://doc.ozforensics.com/oz-knowledge/general/integration-quick-start-guides/how-to-perform-a-face-matching-analysis/face-matching-in-api-6.8.0-and-below.md).
{% endhint %}

The whole transaction takes two calls to Oz API:

1. Your backend gets a `session_token` (preparation).
2. Your backend sends OzCapsula together with the reference photo (main call). Oz API runs Liveness (`QUALITY`) and face matching (`BIOMETRY`) in one folder and returns the result.

## Prerequisites

Before you start, check that your integration fits this scenario:

* **Your backend sends the transaction data.** Use the Oz SDK in the capture mode: the SDK returns OzCapsula to your app, and your app passes it to your backend. Sending the data to Oz API directly from the SDK doesn't apply here.
* **The reference photo comes from a source you trust.** How you obtain the photo and protect it on its way to your backend is your responsibility.
* **The reference photo never goes to the user's device.** Your backend sends it to Oz API directly.
* **Your backend sends one reference photo per request,** in JPEG format. The photo must meet the [media quality requirements](https://doc.ozforensics.com/oz-knowledge/other/media-quality-requirements.md).
* **The user that sends the request can run face matching:** the `can_start_analysis_biometry` flag is on for this user (on by default; see [User Roles](https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/api/oz-api/user-roles.md)).
* **The OzCapsula mandatory parameters are set**. Define them in your API configuration file.

## Flow

{% code title="" expandable="true" %}

```bash
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
```

{% endcode %}

{% stepper %}
{% step %}

#### (your backend) Obtain a `session_token`

Request a session token before each capture session, as close to the moment the user starts capture as possible, and pass it to the device.

```shell
curl --location -g --request POST '{{host}}/api/authorize/session_token' \
--header 'X-Forensic-Access-Token: {{access_token}}'
```

In Instant API, the `X-Forensic-Access-Token` header is optional.

**Response:**

```json
{
  "session_token": "<session_token>"
}
```

The token is short-lived (default lifetime in Full API: 900 seconds, Instant API: 120 seconds). Don't cache it or reuse it across capture sessions.
{% endstep %}

{% step %}

#### (Oz SDK) Capture the Liveness video and get OzCapsula

Add the Liveness (`QUALITY`) analysis to the capture request, then launch the capture with the `session_token`. When the capture is done, take OzCapsula and send it to your backend as is, as `application/octet-stream`.

{% hint style="warning" %}
Don't add a face matching analysis or a reference photo on the device side. If OzCapsula already contains a `BIOMETRY` analysis, Oz API rejects a request with the `biometry_reference` query parameter, so that one folder doesn't get two face matching analyses.
{% endhint %}

{% tabs %}
{% tab title="Android SDK" %}

```kotlin
val captureRequest = CaptureRequest(
    listOf(
        AnalysisProfile(
            Analysis.Type.QUALITY,
            listOf(MediaRequest.ActionMedia(OzAction.Blank))
        )
    )
)
val intent = OzLivenessSDK.createMediaCaptureScreen(captureRequest, sessionToken)
startActivityForResult(intent, REQUEST_LIVENESS_CONTAINER)

// in onActivityResult, on OzLivenessResultCode.SUCCESS:
val container = OzLivenessSDK.getContainerFromIntent(data)
// send the container to your backend
```

Don't run the analysis from the SDK (`addContainer(container)` … `run()`).
{% endtab %}

{% tab title="iOS SDK" %}

```swift
let mediaRequest = MediaRequest.action(.selfie)

let profile = AnalysisProfile(
    mediaList: [mediaRequest],
    type: .quality,
    params: [:]
)

let request = CaptureRequest(
    analysisProfileList: [profile],
    cameraPosition: .front
)

let ozLivenessVC = try OZSDK.createMediaCaptureScreen(self, request, sessionToken: sessionToken)
ozLivenessVC.modalPresentationStyle = .fullScreen
parent.present(ozLivenessVC, animated: true)

// LivenessDelegate: on success, you receive the container
func onResult(container: DataContainer) {
    // send the container to your backend
}
```

Don't run the analysis from the SDK (`addContainer(container)` … `run()`).
{% endtab %}

{% tab title="Web SDK" %}
In the Web SDK configuration file, set `use_wasm_container: true`, `architecture: "capture"`, and `api_use_session_token: "client"` (see [Using OzCapsula in Web SDK](https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/sdk/oz-liveness-websdk/using-ozcapsula-data-container-in-web-sdk)). The SDK returns the container as the second argument of `on_capture_complete`.

```javascript
OzLiveness.open({
    session_token,
    action: ['video_selfie_blank'],
    on_capture_complete: function (result, container) {
        // container: Blob, application/octet-stream
        sendToYourBackend(container);
    },
    // ... other options
});
```

{% endtab %}
{% endtabs %}

OzCapsula is an encrypted container: you can't read or change its content. Don't add anything to it or repack it.
{% endstep %}

{% step %}

#### (your backend) Get the reference photo

Take the reference photo from your trusted source. One photo, in JPEG format.

You're responsible for how you obtain the reference photo and how you protect it until it reaches your backend.
{% endstep %}

{% step %}

#### (your backend) Send OzCapsula and the reference photo in one request

Call `POST /api/folders/` (Full API) or `POST /api/instant/folders/` (Instant API) with the `biometry_reference` query parameter. The request body is `multipart/form-data` with two parts: OzCapsula and the reference photo.

| Parameter            | Values              | Description                                                                                                                                                                                                                                                                                                                                                  |
| -------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `biometry_reference` | `photo`, `document` | <p>Tells Oz API to run face matching and what the reference photo is:</p><ul><li><code>photo</code>: a photo of the person; Oz API tags it <code>photo\_selfie</code>.</li><li><code>document</code>: the front page of an ID document, with the person's photo; Oz API tags it <code>photo\_id\_front</code>.</li></ul><p>Case-sensitive. Pass it once.</p> |

Oz API tells the parts apart by their content: part names, file names, part `Content-Type` and the order of parts don't affect processing.

Don't pass media tags or analysis types: Oz API sets the tags and analyses itself.

{% tabs %}
{% tab title="cURL" %}

```shell
curl --location '{{host}}/api/folders/?biometry_reference=photo' \
--header 'X-Forensic-Access-Token: {{access_token}}' \
--form 'capsula=@"/path/to/capsula.dat"' \
--form 'photo=@"/path/to/reference.jpeg"'
```

{% endtab %}

{% tab title="HTTP" %}

```http
POST /api/folders/?biometry_reference=photo HTTP/1.1
Host: {{host}}
X-Forensic-Access-Token: {{access_token}}
Content-Type: multipart/form-data; boundary=----OzBoundary7MA4YWxkTrZu0gW

------OzBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="capsula"; filename="capsula.dat"
Content-Type: application/octet-stream

<OzCapsula binary content>
------OzBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="photo"; filename="reference.jpeg"
Content-Type: image/jpeg

<reference photo binary content>
------OzBoundary7MA4YWxkTrZu0gW--
```

{% endtab %}
{% endtabs %}

For Instant API, use `/api/instant/folders/` in the same request.
{% endstep %}

{% step %}

#### (Oz API) Get the result

Oz API runs two analyses in one folder:

| Analysis                   | Media used                                                                                                          |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `QUALITY` (Liveness)       | Original media with the user's gesture and the lossless frames from OzCapsula.                                      |
| `BIOMETRY` (face matching) | Original media with the user's gesture and your reference photo. No lossless frames or other images from OzCapsula. |

On success, Oz API returns `201` and the data of the whole folder, in the same format as when you send OzCapsula alone as `application/octet-stream`.

If any of the analyses is `DECLINED`, the folder's `system_resolution` is `DECLINED`. The folder's `resolution_status` is still `FINISHED`.
{% endstep %}
{% endstepper %}

## Errors

If the user that sends a request with `biometry_reference` can't run face matching (`can_start_analysis_biometry` is off), Oz API returns `403`.

Other errors return `400` with the `error_code` and `error_message` below. With `403` and with the `error_code` `4` errors listed here, Oz API doesn't create the folder and doesn't run any analysis.

{% hint style="info" %}
`error_code` `3` and `4` are also used for [OzCapsula errors](https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/api/oz-api/http-return-codes.md#ozcapsula-errors) with other messages. Use `error_message` to tell them apart.
{% endhint %}

| `error_code` | `error_message`                                                                       | Cause                                                                                                                                                                                                                                       |
| ------------ | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `3`          | `Maximum count of attachments = <N> exceed`                                           | The request has more parts than `OZ_ATTACHMENT_MAX_COUNT` (see [Configuration](https://doc.ozforensics.com/oz-knowledge/guides/administrator-guide/configuration/configuration.md)). Every part counts, including parts with the same name. |
| `3`          | `Maximum size of single attachment = <N> exceed`                                      | A part is larger than `OZ_ATTACHMENT_MAX_SIZE`, the maximum size of a single attachment.                                                                                                                                                    |
| `4`          | `Only one reference image is accepted, got <N>`                                       | The request has more than one image.                                                                                                                                                                                                        |
| `4`          | `The reference image must be JPEG, got <mime>`                                        | The reference photo isn't JPEG.                                                                                                                                                                                                             |
| `4`          | `biometry_reference needs a multipart/form-data body with the reference image`        | `biometry_reference` is passed with OzCapsula sent as `application/octet-stream`.                                                                                                                                                           |
| `4`          | `biometry_reference is given <N> times, expected once`                                | `biometry_reference` is passed more than once.                                                                                                                                                                                              |
| `4`          | `Invalid biometry_reference: '<value>', expected one of ['document', 'photo']`        | The `biometry_reference` value isn't `photo` or `document`.                                                                                                                                                                                 |
| `4`          | `biometry_reference is given, but there is no reference image`                        | `biometry_reference` is passed, but there's no image.                                                                                                                                                                                       |
| `4`          | `A reference image is given without biometry_reference`                               | OzCapsula and an image are sent without `biometry_reference`.                                                                                                                                                                               |
| `4`          | `The OzCapsula asks for a BIOMETRY analysis itself, biometry_reference is given too`  | OzCapsula already contains a `BIOMETRY` analysis.                                                                                                                                                                                           |
| `4`          | `The OzCapsula carries no media with the gesture to compare the reference photo with` | OzCapsula has no media with the user's gesture.                                                                                                                                                                                             |
| `13`         | `Invalid request data` or `Invalid Data Container`                                    | `biometry_reference` is present, but there's no OzCapsula in the request.                                                                                                                                                                   |
| `14`         | `Invalid request data` or `Invalid Data Container`                                    | OzCapsula is invalid. In Full API, Oz API still creates the folder.                                                                                                                                                                         |

If the reference photo is unsuitable for face matching, Oz API handles it the same way as any reference photo uploaded to a folder.

#### Requests without `biometry_reference`

* A `multipart/form-data` request with one OzCapsula and nothing else runs the analyses that OzCapsula defines. For a Liveness OzCapsula, this is `QUALITY` only.
* An `application/octet-stream` request with one OzCapsula works as before. It can't carry a reference photo, so `biometry_reference` isn't supported with it.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://doc.ozforensics.com/oz-knowledge/general/integration-quick-start-guides/how-to-perform-a-face-matching-analysis.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
