# Single Request

## Overview and Benefits

In version 6.0.1, we introduced a new feature which allows you to send all required data and receive the analysis result within a single request.

Before 6.0.1, interacting with the API required multiple requests: you had to [create a folder and upload media to it](/oz-knowledge/guides/developer-guide/api/oz-api/use-cases/uploading-media.md), initiate analyses (see [Liveness](/oz-knowledge/guides/developer-guide/api/oz-api/basic-scenarios/liveness.md), [Biometry](/oz-knowledge/guides/developer-guide/api/oz-api/basic-scenarios/biometry.md), and [Blacklist](/oz-knowledge/guides/developer-guide/api/oz-api/basic-scenarios/collection.md)), and then either poll for results or [use webhooks](/oz-knowledge/guides/developer-guide/api/oz-api/use-cases/using-a-webhook-to-get-results.md) for notifications when the result was ready. This flow is still supported, so if you need to send separate requests, you can continue using the existing methods that are listed above.

However, the new API operation mode significantly simplifies the process by allowing you to send a single request and receive the response synchronously. The key benefits are:

* Single request for everything – all data is sent in one package, eliminating the risk of data loss.
* Synchronous response – no need for polling or webhooks to retrieve results.
* High performance – supports up to 36 analyses per minute per instance.

## Usage

To use this method, call `POST /api/folders/`. In the X-Forensic-Access-Token header, pass your [access token](/oz-knowledge/guides/developer-guide/api/oz-api/use-cases/authentication.md). Add media files to the request body and define the tags and metadata if needed in the payload part.

#### Request Example

{% code title="" %}

```json
{
  // (optional block) folder metadata if needed
  "folder:meta_data": {
    "partner_side_folder_id": "00000000-0000-0000-0000-000000000000",
    "person_info": {
      "first_name": "John",
      "middle_name": "Jameson",
      "last_name": "Doe"
    }
  },
  // (optional block) folder metadata if needed
  "media:meta_data": {
    "video1": {
      "foo": "bar"
    }
  },
  "media:tags": {
    "video1": [
      "video_selfie",
      "video_selfie_eyes",
      "orientation_portrait"
    ]
  },
  "analyses": [
    {
      "type": "quality",
      // (optional block) folder metadata if needed
      "meta_data": {
        "example1": "some_example1"
      },
      // additional parameters
      "params": {
        "threshold_spoofing": 0.5,
        "extract_best_shot": false
      }
    }
  ]
}
```

{% endcode %}

#### **Response Example**

```json
{
  "company_id": "00000000-0000-0000-0000-000000000000",
  "time_created": 1744017549.366616,
  "folder_id": "00000000-0000-0000-0000-000000000000",
  "user_id": "00000000-0000-0000-0000-000000000000",
  "resolution_endpoint": null,
  "resolution_status": "FINISHED",
  "resolution_comment": "[]",
  "system_resolution": "SUCCESS",
  ...
  // folder metadata if you've added it
  "meta_data": {
    "partner_side_folder_id": "00000000-0000-0000-0000-000000000000",
    "person_info": {
      "first_name": "John",
      "middle_name": "Jameson",
      "last_name": "Doe"
    }
  },
  "media": [
    {
      "company_id": "00000000-0000-0000-0000-000000000000",
      "folder_id": "00000000-0000-0000-0000-000000000000",
      "folder_time_created": 1744017549.366616,
      "original_name": "00000000-0000-0000-0000-000000000000.mp4",
      "original_url": null,
      "media_id": "00000000-0000-0000-0000-000000000000",
      "media_type": "VIDEO_FOLDER",
      "tags": "video1": [
		"video_selfie",
		"video_selfie_eyes",
		"orientation_portrait"
	]
      "info": {},
      "time_created": 1744017549.368665,
      "time_updated": 1744017549.36867,
	  // media metadata if you've added it
      "meta_data": {
        "foo": "bar"
      },
      "thumb_url": null,
      "image_id": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "time_updated": 1744017549.366629,
  "analyses": [
    {
      "company_id": "00000000-0000-0000-0000-000000000000",
      "group_id": "00000000-0000-0000-0000-000000000000",
      "folder_id": "00000000-0000-0000-0000-000000000000",
      "folder_time_created": 1744017549.366616,
      "analysis_id": "00000000-0000-0000-0000-000000000000",
      "state": "FINISHED",
      "resolution_operator": null,
      "results_media": [
        {
         ...
        }
      ],
      "results_data": null,
	  // analysis metadata if you've added it
      "meta_data": {
        "example1": "some_example1"
      },
      "time_created": 1744017549.369485,
      "time_updated": 1744017550.659305,
      "error_code": null,
      "error_message": null,
      "source_media": [
        {
	 ...
        }
      ],
      "type": "QUALITY",
      "analyse_id": "00000000-0000-0000-0000-000000000000",
      "resolution_status": "SUCCESS",
      "resolution": "SUCCESS"
    }
  ]
}
```

In response, you receive analysis results.

You're done.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/api/oz-api/single-request.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.