Subsection: Folder [LIST] Method (GET)

Folder [LIST] method is used to view all folders available to the user in the system and filter them by retrieved results.

Additional Request Parameters.

All parameters for this method are optional and can be added to the request headline, as necessary.

Visual parameters:

offset=;
Numeric parameter: data paging offset in reference to the start of a list, default value is 0;
limit=;
Numeric parameter that defines the maximal number of output folders; default value is 100;
sorting=;
Sorting the output results by time of creation/update, following options are available:
- time_created{asc} - by creation time, older first;
- time_created{desc} - by creation time, newer first;
- time_updated{asc} - by update time, older first;
- time_updated{desc} - by update time, newer first.

Filtering the Output:

time_created.max=;
The latest creation time of the folder in UNIX TIMESTAMP format; this parameter is used together with time_created.min;
time_created.min=;
The earliest creation time of the folder in UNIX TIMESTAMP format; this parameter its used together with time_created.max;
time_updated.max=;
The latest creation update time of the folder in UNIX TIMESTAMP format; this parameter is used together with time_updated.min;
time_updated.min=;
The earliest update time of the folder in UNIX TIMESTAMP format; this parameter is used together with time_created.min;
meta_data=;
Text search in folder metadata; following operators are available:
- «==» - equality;
- «!=» - inequality.
resolution_status=;
Filtering by the folder status, following options are available:
- INITIAL – Initial status.
- PROCESSING – Analyzers are processing data.
- FAILED – A technical or logical failure occurred during the analyzers’ work.
- FINISHED – Data processing is finished.
- DECLINED – A negative resolution is taken for the folder (images/videos contained in the folder do not match the quality criteria).
- SUCCESS – A positive resolution is taken for the folder.
resolution_status.exclude=;
Filtering by the folder status, exclusive parameter. Statuses specified with this parameter will not appear in the search results;
folder_id=;
Filtering by the folder unique identifier;
folder_id.exclude=;
Filtering by the folder unique identifier, exclusive parameter. IDs specified with this parameter will not appear in the search results.

Output of additional information in the response:

with_analyses=true;
Enabling this parameter will display analysis results in the JSON response of the relevant method similarly to Folder Analyses [LIST] method;
with_user=true;
Enabling this parameter will display information on the user who created the folder in the JSON response;
with_company=true;
Enabling this parameter will display information on the company that created the user's folder in the JSON response;

Request Examples.

Example of running the Folder [LIST] method in Postman:

Examples of GET request syntax using Folder [LIST] method with following parameters:

Descending sorting by folder creation time;
Display of 3 results at the most;
Display of user who created folders;
Exclusion of folder with ID “906f6898-048e-4192-8c09-a1853b6f59b9” of displayed results;
Entry “iin” is present in metadata and has the value “test11234567”.

HTTP

Bash

Python

php

Java


GET /api/folders/?limit=3& sorting=time_created{desc}& meta_data=iin==test11234567& folder_id.exclude=906f6898-048e-4192-8c09-a1853b6f59b9& with_user=true HTTP/1.1
Host: youradress.ru
X-Forensic-Access-Token: 0ccbdb4627c9d07c6c5b8f6e6cca44b5f8cb0c54ad7659098fa336240d494b0f9035e14bc42fc461224a9719f105e41026fed0f6f14188d9107b8c3d697a0cb1
User-Agent: PostmanRuntime/7.15.2
Accept: */*
Cache-Control: no-cache
Postman-Token: 8248323a-3e32-41cd-98cb-215fe70bb57f,cd290740-68a1-4a07-81ed-da35819a8602
Host: youradress.ru
Accept-Encoding: gzip, deflate
Connection: keep-alive
cache-control: no-cache


curl -X GET \
  'https://youradress.ru/api/folders/?limit=3&sorting=time_created{desc}&meta_data=iin==test11234567&folder_id.exclude=906f6898-048e-4192-8c09-a1853b6f59b9&with_user=true' \
  -H 'Accept: */*' \
  -H 'Accept-Encoding: gzip, deflate' \
  -H 'Cache-Control: no-cache' \
  -H 'Connection: keep-alive' \
  -H 'Host: youradress.ru' \
  -H 'Postman-Token: 8248323a-3e32-41cd-98cb-215fe70bb57f,48cf855e-cf80-4bda-abe4-a43a307d596f' \
  -H 'User-Agent: PostmanRuntime/7.15.2' \
  -H 'X-Forensic-Access-Token: 0ccbdb4627c9d07c6c5b8f6e6cca44b5f8cb0c54ad7659098fa336240d494b0f9035e14bc42fc461224a9719f105e41026fed0f6f14188d9107b8c3d697a0cb1' \
  -H 'cache-control: no-cache'


import requests

url = "https://youradress.ru/api/folders/"

querystring = {"limit":"3","sorting":"time_created{desc}","meta_data":"iin==test11234567","folder_id.exclude":"906f6898-048e-4192-8c09-a1853b6f59b9","with_user":"true"}

headers = {
    'X-Forensic-Access-Token': "0ccbdb4627c9d07c6c5b8f6e6cca44b5f8cb0c54ad7659098fa336240d494b0f9035e14bc42fc461224a9719f105e41026fed0f6f14188d9107b8c3d697a0cb1",
    'User-Agent': "PostmanRuntime/7.15.2",
    'Accept': "*/*",
    'Cache-Control': "no-cache",
    'Postman-Token': "8248323a-3e32-41cd-98cb-215fe70bb57f,d9e635d6-42ea-4948-9337-49e1920e2224",
    'Host': "youradress.ru",
    'Accept-Encoding': "gzip, deflate",
    'Connection': "keep-alive",
    'cache-control': "no-cache"
    }

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)


setUrl('https://youradress.ru/api/folders/');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'limit' => '3',
  'sorting' => 'time_created{desc}',
  'meta_data' => 'iin==test11234567',
  'folder_id.exclude' => '906f6898-048e-4192-8c09-a1853b6f59b9',
  'with_user' => 'true'
));

$request->setHeaders(array(
  'cache-control' => 'no-cache',
  'Connection' => 'keep-alive',
  'Accept-Encoding' => 'gzip, deflate',
  'Host' => 'youradress.ru',
  'Postman-Token' => '8248323a-3e32-41cd-98cb-215fe70bb57f,6d8e5f47-d580-4f05-baad-61414ff59847',
  'Cache-Control' => 'no-cache',
  'Accept' => '*/*',
  'User-Agent' => 'PostmanRuntime/7.15.2',
  'X-Forensic-Access-Token' => '0ccbdb4627c9d07c6c5b8f6e6cca44b5f8cb0c54ad7659098fa336240d494b0f9035e14bc42fc461224a9719f105e41026fed0f6f14188d9107b8c3d697a0cb1'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}


OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://youradress.ru/api/folders/?limit=3&sorting=time_created{desc}&meta_data=iin==test11234567&folder_id.exclude=906f6898-048e-4192-8c09-a1853b6f59b9&with_user=true")
  .get()
  .addHeader("X-Forensic-Access-Token", "0ccbdb4627c9d07c6c5b8f6e6cca44b5f8cb0c54ad7659098fa336240d494b0f9035e14bc42fc461224a9719f105e41026fed0f6f14188d9107b8c3d697a0cb1")
  .addHeader("User-Agent", "PostmanRuntime/7.15.2")
  .addHeader("Accept", "*/*")
  .addHeader("Cache-Control", "no-cache")
  .addHeader("Postman-Token", "8248323a-3e32-41cd-98cb-215fe70bb57f,69c8f046-2903-45b6-bd44-b57cd658bfe6")
  .addHeader("Host", "youradress.ru")
  .addHeader("Accept-Encoding", "gzip, deflate")
  .addHeader("Connection", "keep-alive")
  .addHeader("cache-control", "no-cache")
  .build();

Response response = client.newCall(request).execute();

Example of JSON Response.

Example of the system's JSON response to calling Folder [LIST] method with similar parameters:

JSON


{
    "offset": 0,
    "limit": 3,
    "total_count": 4,
    "items": [
        {
            "time_created": 1579681651,
            "time_updated": 1579681651,
            "meta_data": {
                "iin": "test11234567"
            },
            "folder_id": "7074a87e-3c65-423f-99a9-d21324e75395",
            "resolution_time": null,
            "resolution_status": "INITIAL",
            "resolution_endpoint": null,
            "resolution_state_hash": "453e0aa12c7bbd05",
            "resolution_comment": null,
            "resolution_suggest": null,
            "resolution_author_id": null,
            "is_archive": false,
            "media": [
                {
                    "time_created": 1579681651,
                    "time_updated": 1579681651,
                    "meta_data": {},
                    "media_id": "052c8748-b4ef-4f0f-8ea5-17297552a92d",
                    "media_type": "IMAGE_FOLDER",
                    "info": {
                        "thumb": {
                            "md5": "933fa1f5dd44d2c43f75e8044d4fa7a1",
                            "size": 17070,
                            "width": 300,
                            "height": 280,
                            "mime-type": "image/jpeg"
                        },
                        "original": {
                            "md5": "54b5d75d01488817bf041a5273de4585",
                            "size": 50971,
                            "width": 445,
                            "height": 416,
                            "mime-type": "image/jpeg"
                        }
                    },
                    "tags": [
                        "photo_selfie"
                    ],
                    "original_name": "2.jpg",
                    "image_id": "052c8748-b4ef-4f0f-8ea5-17297552a92d",
                    "original_url": "http://youradress.ru/static/7074a87e-3c65-423f-99a9-d21324e75395/052c8748-b4ef-4f0f-8ea5-17297552a92d.jpeg",
                    "thumb_url": "http://youradress.ru/static/7074a87e-3c65-423f-99a9-d21324e75395/052c8748-b4ef-4f0f-8ea5-17297552a92d_thumb.jpeg"
                },
                {
                    "time_created": 1579681651,
                    "time_updated": 1579681651,
                    "meta_data": {},
                    "media_id": "af4da4fe-61b1-49ea-bea1-3d5bde57a205",
                    "media_type": "IMAGE_FOLDER",
                    "info": {
                        "thumb": {
                            "md5": "1827f89da365f01a24deb0329d231f80",
                            "size": 18261,
                            "width": 300,
                            "height": 300,
                            "mime-type": "image/jpeg"
                        },
                        "original": {
                            "md5": "9b1393886e54d93e1303ff284ae4dedf",
                            "size": 147204,
                            "width": 492,
                            "height": 492,
                            "mime-type": "image/jpeg"
                        }
                    },
                    "tags": [
                        "photo_id"
                    ],
                    "original_name": "1.jpg",
                    "image_id": "af4da4fe-61b1-49ea-bea1-3d5bde57a205",
                    "original_url": "http://youradress.ru/static/7074a87e-3c65-423f-99a9-d21324e75395/af4da4fe-61b1-49ea-bea1-3d5bde57a205.jpeg",
                    "thumb_url": "http://youradress.ru/static/7074a87e-3c65-423f-99a9-d21324e75395/af4da4fe-61b1-49ea-bea1-3d5bde57a205_thumb.jpeg"
                }
            ],
            "user": {
                "user_id": "7b10dac0-e6ac-4138-a1af-c6cb2addcce1",
                "user_type": "CLIENT",
                "first_name": "FAQTest",
                "last_name": "FAQTest",
                "middle_name": "",
                "email": "manualtest@oz-services.ru",
                "can_start_analyse_biometry": true,
                "can_start_analyse_collection": true,
                "can_start_analyse_documents": true,
                "can_start_analyse_forensic": true,
                "can_start_analyse_kyc": true,
                "can_start_analyse_quality": true,
                "company_id": "d5b935aa-6745-47b6-a72d-20a418116a29",
                "is_admin": false,
                "is_service": true
            }
        },
        {
            "time_created": 1579681651,
            "time_updated": 1579681651,
            "meta_data": {
                "iin": "test11234567"
            },
            "folder_id": "2dce78c6-833b-4016-b8ad-d44dc03bcb9c",
            "resolution_time": null,
            "resolution_status": "INITIAL",
            "resolution_endpoint": null,
            "resolution_state_hash": "e0b8a094c4c87428",
            "resolution_comment": null,
            "resolution_suggest": null,
            "resolution_author_id": null,
            "is_archive": false,
            "media": [
                {
                    "time_created": 1579681651,
                    "time_updated": 1579681651,
                    "meta_data": {},
                    "media_id": "35854e01-75e4-44a0-a20d-e75ecc4ae4cd",
                    "media_type": "IMAGE_FOLDER",
                    "info": {
                        "thumb": {
                            "md5": "933fa1f5dd44d2c43f75e8044d4fa7a1",
                            "size": 17070,
                            "width": 300,
                            "height": 280,
                            "mime-type": "image/jpeg"
                        },
                        "original": {
                            "md5": "54b5d75d01488817bf041a5273de4585",
                            "size": 50971,
                            "width": 445,
                            "height": 416,
                            "mime-type": "image/jpeg"
                        }
                    },
                    "tags": [
                        "photo_selfie"
                    ],
                    "original_name": "2.jpg",
                    "image_id": "35854e01-75e4-44a0-a20d-e75ecc4ae4cd",
                    "original_url": "http://youradress.ru/static/2dce78c6-833b-4016-b8ad-d44dc03bcb9c/35854e01-75e4-44a0-a20d-e75ecc4ae4cd.jpeg",
                    "thumb_url": "http://youradress.ru/static/2dce78c6-833b-4016-b8ad-d44dc03bcb9c/35854e01-75e4-44a0-a20d-e75ecc4ae4cd_thumb.jpeg"
                },
                {
                    "time_created": 1579681651,
                    "time_updated": 1579681651,
                    "meta_data": {},
                    "media_id": "679cc0c4-8701-4b09-8108-77aaf6ec70ff",
                    "media_type": "IMAGE_FOLDER",
                    "info": {
                        "thumb": {
                            "md5": "1827f89da365f01a24deb0329d231f80",
                            "size": 18261,
                            "width": 300,
                            "height": 300,
                            "mime-type": "image/jpeg"
                        },
                        "original": {
                            "md5": "9b1393886e54d93e1303ff284ae4dedf",
                            "size": 147204,
                            "width": 492,
                            "height": 492,
                            "mime-type": "image/jpeg"
                        }
                    },
                    "tags": [
                        "photo_id"
                    ],
                    "original_name": "1.jpg",
                    "image_id": "679cc0c4-8701-4b09-8108-77aaf6ec70ff",
                    "original_url": "http://youradress.ru/static/2dce78c6-833b-4016-b8ad-d44dc03bcb9c/679cc0c4-8701-4b09-8108-77aaf6ec70ff.jpeg",
                    "thumb_url": "http://youradress.ru/static/2dce78c6-833b-4016-b8ad-d44dc03bcb9c/679cc0c4-8701-4b09-8108-77aaf6ec70ff_thumb.jpeg"
                }
            ],
            "user": {
                "user_id": "7b10dac0-e6ac-4138-a1af-c6cb2addcce1",
                "user_type": "CLIENT",
                "first_name": "FAQTest",
                "last_name": "FAQTest",
                "middle_name": "",
                "email": "manualtest@oz-services.ru",
                "can_start_analyse_biometry": true,
                "can_start_analyse_collection": true,
                "can_start_analyse_documents": true,
                "can_start_analyse_forensic": true,
                "can_start_analyse_kyc": true,
                "can_start_analyse_quality": true,
                "company_id": "d5b935aa-6745-47b6-a72d-20a418116a29",
                "is_admin": false,
                "is_service": true
            }
        },
        {
            "time_created": 1579681650,
            "time_updated": 1579681650,
            "meta_data": {
                "iin": "test11234567"
            },
            "folder_id": "169de252-9da2-4b43-9f39-0fee6fbe1be1",
            "resolution_time": null,
            "resolution_status": "INITIAL",
            "resolution_endpoint": null,
            "resolution_state_hash": "6fcaad33b3fa21a7",
            "resolution_comment": null,
            "resolution_suggest": null,
            "resolution_author_id": null,
            "is_archive": false,
            "media": [
                {
                    "time_created": 1579681650,
                    "time_updated": 1579681650,
                    "meta_data": {},
                    "media_id": "77e754f1-b7f7-44c3-bd48-0bdc0ac2b3dd",
                    "media_type": "IMAGE_FOLDER",
                    "info": {
                        "thumb": {
                            "md5": "933fa1f5dd44d2c43f75e8044d4fa7a1",
                            "size": 17070,
                            "width": 300,
                            "height": 280,
                            "mime-type": "image/jpeg"
                        },
                        "original": {
                            "md5": "54b5d75d01488817bf041a5273de4585",
                            "size": 50971,
                            "width": 445,
                            "height": 416,
                            "mime-type": "image/jpeg"
                        }
                    },
                    "tags": [
                        "photo_selfie"
                    ],
                    "original_name": "2.jpg",
                    "image_id": "77e754f1-b7f7-44c3-bd48-0bdc0ac2b3dd",
                    "original_url": "http://youradress.ru/static/169de252-9da2-4b43-9f39-0fee6fbe1be1/77e754f1-b7f7-44c3-bd48-0bdc0ac2b3dd.jpeg",
                    "thumb_url": "http://youradress.ru/static/169de252-9da2-4b43-9f39-0fee6fbe1be1/77e754f1-b7f7-44c3-bd48-0bdc0ac2b3dd_thumb.jpeg"
                },
                {
                    "time_created": 1579681650,
                    "time_updated": 1579681650,
                    "meta_data": {},
                    "media_id": "4bb5a786-b495-4af5-bf33-fd94e32281d1",
                    "media_type": "IMAGE_FOLDER",
                    "info": {
                        "thumb": {
                            "md5": "1827f89da365f01a24deb0329d231f80",
                            "size": 18261,
                            "width": 300,
                            "height": 300,
                            "mime-type": "image/jpeg"
                        },
                        "original": {
                            "md5": "9b1393886e54d93e1303ff284ae4dedf",
                            "size": 147204,
                            "width": 492,
                            "height": 492,
                            "mime-type": "image/jpeg"
                        }
                    },
                    "tags": [
                        "photo_id"
                    ],
                    "original_name": "1.jpg",
                    "image_id": "4bb5a786-b495-4af5-bf33-fd94e32281d1",
                    "original_url": "http://youradress.ru/static/169de252-9da2-4b43-9f39-0fee6fbe1be1/4bb5a786-b495-4af5-bf33-fd94e32281d1.jpeg",
                    "thumb_url": "http://youradress.ru/static/169de252-9da2-4b43-9f39-0fee6fbe1be1/4bb5a786-b495-4af5-bf33-fd94e32281d1_thumb.jpeg"
                }
            ],
            "user": {
                "user_id": "7b10dac0-e6ac-4138-a1af-c6cb2addcce1",
                "user_type": "CLIENT",
                "first_name": "FAQTest",
                "last_name": "FAQTest",
                "middle_name": "",
                "email": "manualtest@oz-services.ru",
                "can_start_analyse_biometry": true,
                "can_start_analyse_collection": true,
                "can_start_analyse_documents": true,
                "can_start_analyse_forensic": true,
                "can_start_analyse_kyc": true,
                "can_start_analyse_quality": true,
                "company_id": "d5b935aa-6745-47b6-a72d-20a418116a29",
                "is_admin": false,
                "is_service": true
            }
        }
    ]
}

Details of JSON Response.

First block of the response (strings 2–4) contains general information. We can see that 4 folders were found for the request, but only 3 of them are displayed:

"limit": 3,
"total_count": 4.

Block "items" (strings 5–292) contains main information on folders.

For each folder a general information block is displayed first (strings 7–20).

Block "media" (strings 21–82) contains information on files stored in folders.

Block "user" (strings 83–100) contains information on the user who created the folder.