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, initiate analyses (see Liveness, Biometry, and Blacklist), and then either poll for results or use webhooks 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. Add media files to the request body and define the tags and metadata if needed in the payload part.

Request payload example

{
  // (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
      }
    }
  ]
}

Response Example

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