> 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/guides/developer-guide/api/oz-api/metadata.md).

# Metadata

## Overview

Metadata is any optional data you might need to add to a [system object](/oz-knowledge/guides/developer-guide/api/oz-api/system-objects.md). In the `meta_data` section, you can include any information you want, simply by providing any number of fields with their values:

```json
…
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.

| **Object** | **API Method**                                                                                                                                                                                                    |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| User       | `PATCH /api/users/{{user_id}}`                                                                                                                                                                                    |
| Folder     | `PATCH /api/folders/{{folder_id}}/meta_data/`                                                                                                                                                                     |
| Media      | `PATCH /api/media/{{media_id}}/meta_data`                                                                                                                                                                         |
| Analysis   | `PATCH /api/analyses/{{analyse_id}}/meta_data`                                                                                                                                                                    |
| Collection | <p><code>PATCH /api/collections/{{collection\_id}}/meta\_data/</code></p><p>and, for a person in a collection,</p><p><code>PATCH /api/collections/{{collection\_id}}/persons/{{person\_id}}/meta\_data</code></p> |

You can also change or delete metadata. Please refer to our [API documentation](https://apidoc.ozforensics.com/).

## Usage examples

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:

```json
{
  "iin": "123123123"
}
```

{% hint style="info" %}
You can pass an ID of a person in this field, and use this ID to combine requests with the same person and count unique persons (same ID = same person, different IDs = different persons). This ID can be a phone number, an IIN, an SSN, or any other kind of unique ID. The ID will be displayed in the report as an additional column.
{% endhint %}

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 [here](/oz-knowledge/guides/developer-guide/sdk/oz-liveness-websdk/web-plugin/security-recommendations.md#retrieve-the-analysis-response-and-process-it-on-the-back-end).

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:

* [iOS](/oz-knowledge/guides/developer-guide/sdk/oz-mobile-sdk/ios/checking-liveness-and-face-biometry.md#adding-metadata)
* [Android](/oz-knowledge/guides/developer-guide/sdk/oz-mobile-sdk/android/checking-liveness-and-face-biometry.md#adding-metadata)
* [Web](/oz-knowledge/guides/developer-guide/sdk/oz-liveness-websdk/web-plugin/launching-the-plugin.md)


---

# 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/guides/developer-guide/api/oz-api/metadata.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.