Metadata is any optional data you might need to add to a system object. In the meta_data section, you can include any information you want, simply by providing any number of fields with their values:

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


API Method


PATCH /api/users/{{user_id}}


PATCH /api/folders/{{folder_id}}/meta_data/


PATCH /api/media/{{media_id}}/meta_data


PATCH /api/analyses/{{analyse_id}}/meta_data


PATCH /api/collections/{{collection_id}}/meta_data/

and, for a person in a collection,

PATCH /api/collections/{{collection_id}}/persons/{{person_id}}/meta_data

You can also change or delete metadata. Please refer to our API documentation.

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:

  "iin": "123123123"

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.

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.

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:

Last updated