GATEWAY API SERVER FOR ACCESSING OZ FORENSICS SERVICES · Editing a company profile 24 6.2.10. Deleting a company 24 6.3. Folders 25 6.3.1. Model 25 6.3.2. ... 3XX have ancillary

GATEWAY API SERVER FOR ACCESSING OZ FORENSICS SERVICES

– 1 –

Terms and abbreviations 5

OVERVIEW 6

1. Data communication protocol 6

1.1. Basic specification 6

1.1.1. HTTP response codes 6

1.1.2. Paging 6

1.1.3. Structure of error description 7

1.1.4. Error codes 9

2. Authorization 11

3. Endpoints 11

Specification 12

4. Role model of access control 12

4.1. User model 12

4.2. Company model 12

4.3. User types 13

4.4. Privileges of Company users 13

5. Data model 13

6. List of API methods 14

6.1. Authorization 14

6.1.1. User authentication 14

6.1.2. Account password restore 16

6.1.3. Issue of an authorization token for a support user 17

6.1.4. Re-issue of an authorization token for a support user 18

6.2. Users, companies, user roles 19

6.2.1. Obtaining a general list of user profiles 19

6.2.2. Creating a user account 19

6.2.2.1. Example: Creating a company user account 20

6.2.2.2. Example: Creating a company administrator account 21

6.2.3. Retrieving information about a particular user 22

6.2.4. Editing a user profile 22

– 2 –

6.2.5. Deleting a user 22

6.2.6. Retrieving a general list of companies 23

6.2.7. Creating a company profile 23

6.2.8. Retrieving information about a particular company 23

6.2.9. Editing a company profile 24

6.2.10. Deleting a company 24

6.3. Folders 25

6.3.1. Model 25

6.3.2. Retrieving a general list of folders 26

6.3.3. Creating a new folder with media data 31

6.3.4. Retrieving information about a particular folder 35

6.3.5. Editing folder data 38

6.3.6. Deleting folders 41

6.4. Media files 42

6.4.1. Model 42

6.4.1.1. Images 42

6.4.1.2. Videos 42

6.4.2. Retrieving a list of media files in folder 43

6.4.3. Adding media files to folder 45

6.4.4. Deleting media files from folder 48

6.5. Tagging media files 48

6.5.1. Overview 48

6.5.2. Acceptable tags with descriptions 49

6.6. Analyzers 50

6.6.1. Model 50

6.6.2. Launch of folder analysis 51

6.6.3. Retrieving analysis results 65

6.6.4. Retrieving a particular analysis 69

6.6.5. Deleting an analysis 72

6.6. Metadata 73

6.6.1. Retrieving metadata 73

6.6.2. Setting up metadata 74

– 3 –

6.6.3. Editing metadata 75

6.6.4. Clearing metadata 76

Specifications of analyzers 77

7. Basic error codes 77

8. KYC check service 78

8.1. Input 78

8.2. Output 79

9. Photo expert service 81

9.1. Input parameters 81

9.2. Output parameters 82

10. Document analysis service 85

10.1. General operation logic 85

10.2. Structure of analysis results’ description 86

10.3. Basic constants 88

10.3.1. Possible values for text fields’ verification results 88

10.3.2. Possible values for graphic fields 89

10.3.3. Possible values for text fields 89

11. Biometrics service 103

11.1. Operation logic 103

11.2. Structure of analyzer results’ description 103

– 4 –

Terms and abbreviations

OS Operating system

MNO Mobile network operator

IS Information system

ExIS External information system (in relation to the one being designed)

JSON JavaScript Object Notation, a text data communication protocol based on JavaScript

XML Extended Markup Language, a text data communication protocol

RSA A public key cryptographic algorithm used to encrypt and digitally sign data

SHA A family of cryptosecure hash algorithms

HTTP/HTTPS Application level data transfer protocols

DBMS Data base management system

– 5 –

OVERVIEW 1. Data communication protocol

1.1. Basic specification

Gateway API for accessing Oz Forensic services is plotted using the following approach:

! REST methodology as a general concept

! JSON standard for data transmission coding

1.1.1. HTTP response codes

Each server response must include a correct special HTTP response status, and:

! Response codes 1XX, 3XX have ancillary functions and aren’t described in this specification

! Response codes 2XX indicate a correctly processed request (e.g. code 200 for retrieving data, code 201 for adding a new entity, code 204 for a correct deletion etc.)

! Response codes 4XX indicate that a request couldn’t have been processed correctly because of some client-side data (e.g. 404 for addressing a non-existing resource)

! Response codes 5XX indicate that an IS side error occurred during request processing (e.g. when a DB is temporarily unavailable)

1.1.2. Paging Each data query with a large volume of potential results must have a paging

mechanism:

– 6 –

! Input parameters:

o offset – a data paging offset in reference to the start of a list, default value is 0

o limit – a maximal window of results, default value is 100 (5000 at most)

! Output parameters:

o Items – data fields in form of an array

o offset – offset value applied to the data

o limit – maximal window of results applied to the data

o total_count – total number of records meeting the query criteria

Example: { "items": [ …

], "limit": 100, "offset": 100, "total_count": 102

}

1.1.3. Structure of error description Each error that occurs while processing a request on the IS side, along with

its respective HTTP code, must include also a more detailed description of this error within the response body. Following fields must be specified:

! error_code – integer code of the error

! error_message – a message describing the encountered error (only for debugging tasks and incident investigations)

! details – error details (specification format depends on the error type). This field is optional.

– 7 –

Example: {

"error_code": 0, "error_message": "Unknown server side error

occurred", "details": null

}

– 8 –

1.1.4. Error codes Code Name Description

0 UNKNOWN Unknown server error

1 NOT ALLOWED An invalid method was called; usually this error is accompanied with an HTTP response status 405 when an unsupported method is called (e.g. PATCH in case that a resource only supports GET/POST).

2 NOT REALIZED A web service not implemented for the server was called. This error may occur if a server is present according to documentation but has not been actually implemented as a permanent/temporary solution.

3 INVALID STRUCTURE Invalid request structure. Usually this error occurs when a mandatory parameter cannot be found or the request body was transferred in a wrong format.

4 INVALID VALUE Invalid parameter value, eg.:

! A string was transferred that was alleged to be in UUID format, yet it couldn’t be converted correctly.

! A negative paging offset/window limit value was transferred.

! …

5 INVALID TYPE Invalid data type for the parameter

– 9 –

6 AUTH NOT PROVIDED Authentication parameters are absent. This error may occur at an attempt to request a resource which requires authorization without transferring a respective token/key/signature in the request headers.

7 AUTH INVALID Invalid authentication parameter values. This error may occur when authorization parameters are present but no users (client systems) with these data can be found.

8 AUTH EXPIRED Authentication data are expired. This error may occur when a token/key/signature with an expiration function is used.

9 AUTH FORBIDDEN Current authorized user (client system) is not allowed to access the requested resource. This error may occur:

! At an attempt to request the profile of a different client system.

! At an attempt of the client system to request information about clients not belonging to this system.

! …

10 NOT EXIST Requested resource doesn’t exist (equivalent to HTTP status_code = 404)

– 10 –

11 EXTERNAL SERVICE Error of communication with an external IS. This error may occur in case of problems of communication with any external information systems.

12 DATABASE A critical database operation error on the server side.

2. Authorization

Any request to the system must be accompanied by an authentication token to be added into Header of the HTTP request with the key X-Forensic-Access-

Token.

Example: GET /api/folders/ HTTP/1.1 Host: dev.oz-services.ru X-Forensic-Access-Token: 3f9cab9923e91183ab75fe574db76559ecbdb580cec0aa15881 77647f0b9c69865b5f17823ee98ccb6762b3f477f59d9e26fea ce2b71d157f3c4c18a611b8a6a Cache-Control: no-cache

NB: All examples in the document are provided as HTTP specification.

NB2: An authorization token can be obtained on request. 3. Endpoints

Different servers are used for the test and production API parts, and namely:

! Test server: https://dev.oz-services.ru

! Production server: https://oz.services.ru

– 11 –

Specification 4. Role model of access control

4.1. User model

User model is a registered user profile with a saved pair ‘email address/hash password’ which is used for authentication, and information about the user’s role and status in his/her company which is used to control the user’s access to folders, analysis results and other resources stored in the system.

Attributes of the User model:

● user_id - unique identifier of user ● user_type - a string identifier of the user's role ● company_id - unique identifier of the company to which this user

belongs; not used for ADMIN and OPERATOR system user types ● first_name, last_name, middle_name - component strings for the user’s

full name

● email ● is_admin - flag indicating company administrator privileges; not used

for ADMIN and OPERATOR system user types ● is_service - flag indicating support user privileges; not used for ADMIN

and OPERATOR system user types 4.2. Company model

Company model is a stored profile of a company. In terms the access control role model it is a group of users.

Attributes of the Company model:

● company_id - unique identifier of company

– 12 –

● name - company name 4.3. User types

The system supports pre-defined user types with the following identifiers:

● ADMIN - System administrator. Full access to all system resources via the present API.

● OPERATOR - System operator. Full access to view all resources and the right to assign status to any analysis.

● CLIENT - Company user.

4.4. Privileges of Company users. If is_admin flag is set true, such user is an administrator of the company.

He/she has full access to all stored resources of the company and may manage its accounts.

If is_service flag is set true, such user is a support service user of the company. His/her permissions are equivalent to those of a company user, and he/she has a persistent authorization token. Registration and authorization if users’ data are accomplished via support token API.

5. Data model

Following data model is used for the system operation:

! Folder entity - a logical unit of work with the system that serves as a container for images and videos to be processed

! Image entity - an image that was uploaded or created by the system as a result of processing with analyzers

! Video entity - an video that was uploaded or created by the system as a result of processing with analyzers

– 13 –

! Analyse entity - results of application of an image analysis method to entity Folder and its images. Includes field type for description of analysis type, possible values:

o FORENSIC – an analyzer of photographic compilation in uploaded images

o BIOMETRY – a biometrics analyzer allowing to evaluate the biometric semblance of faces represented in uploaded images

o DOCUMENTS – a content analyzer for documents (like an ID card) represented in uploaded images

o KYC – Know Your Customer analyzer that identifies whether a person is included into prohibitory/sanctions lists by uploaded metadata

o COLLECTION – an analyzer for evaluation the biometric semblance of a person in the image with images from a curated persons’ list (typical scenario: whether a face is present in a black/white list)

6. List of API methods 6.1. Authorization

6.1.1. User authentication Address:

authorize/auth

HTTP method: POST

Purpose: Authentication of a user with a pair email/password and issue of an authorization token

Query format:

– 14 –

Data dictionary comprising credentials dictionary with email and password fields.

Response format:

Data dictionary comprising the following fields:

● user_id: authorized user identifier ● access_token: authorization token value ● expire_date: authorization token expiry time in Unix time format

HTTP status code at successful processing: 200

HTTP status code in case of failed authorization: 401

Example: Request: POST /api/authorize/auth HTTP/1.1 Host: localhost:8000 Content-Type: application/json cache-control: no-cache {

"credentials": { "email": "[email protected]", "password": "admin"

} } Response: {

"session_id": 12, "user_id": "d551d9c6-

ea06-43c7-8251-6e4caa342cd0", "access_token":

"42a8816ada66e96a770b0c463e2cb1169b2d125f1d859be64a aea086cffbe6772da1b930b6fbd396b4f1b4dbc15788444cc9a 6f53739c7a26c7eef217b2eb719",

"expire_token": "5ad9f0e8198b7f3fdc09c44c07e48d1bd346916dd223b2fe45 ee39719ff8bdf6284e56bf53e83e3ae4ca7035f3cf44ef07131 5179fbc32a4bc01ef92c8641c39",

"expire_date": 1550228915, "user": {

"user_id": "d551d9c6- ea06-43c7-8251-6e4caa342cd0",

"user_type": "ADMIN", "first_name": null,

– 15 –

mailto:[email protected]

"last_name": null, "middle_name": null, "email": "[email protected]"

} }

6.1.2. Account password restore Address: authorize/restore

HTTP method: POST

Purpose: Account password recovery request. A recovery code will be sent to the specified user’s email address.

Query format: Data dictionary comprising credentials dictionary with email field


Address: authorize/restore

HTTP method: PATCH

Purpose: Setting account password with a recovery code.

Query format: Data dictionary comprising credentials dictionary with email and password fields.


HTTP status code in case of an invalid recovery code: 404

Example of use: Request: PATCH /api/authorize/restore HTTP/1.1 Host: localhost:8000 Content-Type: application/json cache-control: no-cache {

"credentials": { "restore_code":

"7efc855b128e7c85b2b69b520e60c32d32c63b5b419b8608f1 b8527abb5409a8",

"password": "new_password" }

– 16 –


}

Response: {

"success": true }

6.1.3. Issue of an authorization token for a support user Address: authorize/service_token

HTTP method: GET

Purpose: Obtaining a persistent authorization token allowing to activate clients from services.

Access control: permitted for company administrators


Example of use:

Request:

GET /api/authorize/service_token HTTP/1.1 Host: localhost:8000 X-Forensic-Access-Token: 0fe98b4135bca617ea5b287a48d51a895191c0357de6bd55f67 5f0413cc251b4f1f1e4bb2ca2230d9c13817fec0ddfa773d7c8 84049fdab7a8f48295f5d1159b Content-Type: application/json cache-control: no-cache

Response: {

"session_id": 9, "user_id": "57959bf4-ab08-4044-9555-

ad6389d566a2", "access_token":

"67ddecffce65e551e9adf78d7b4349010d89df4cb89312d412 f8a8561b5090cd31a198059ba1cd0acae705eddbd23badd5c32 524c6e2eebfee16db230d835d9e",

"expire_token": "51ce10b8b4cd93b3688ae70ac851def2a108d27dc001184056 233c42a52e76360587d6c80adcf8d3533fe45c89fd622fa556d bf5037b43fd2663dfd4749fc357",

"expire_date": 1707906864, "user": {

"user_id": "57959bf4-ab08-4044-9555- ad6389d566a2",

"user_type": "CLIENT",

– 17 –

"first_name": null, "last_name": null, "middle_name": null, "email": "ada26a7a-a495-421c-

[email protected]", "company_id": "d85ddf44-72eb-467f-

a4a6-77872babcace", "is_admin": false, "is_service": true

} }

6.1.4. Re-issue of an authorization token for a support user Address: authorize/service_token

HTTP method: PATCH

Purpose: Creating and obtaining a new persistent authorization token allowing to activate clients from services.

Access control: permitted for company administrators


Example of use:

Request:

GET /api/authorize/service_token HTTP/1.1 Host: localhost:8000 X-Forensic-Access-Token: 0fe98b4135bca617ea5b287a48d51a895191c0357de6bd55f67 5f0413cc251b4f1f1e4bb2ca2230d9c13817fec0ddfa773d7c8 84049fdab7a8f48295f5d1159b Content-Type: application/json cache-control: no-cache

Response: {

"session_id": 9, "user_id": "57959bf4-ab08-4044-9555-

ad6389d566a2", "access_token":

"1eb1b7694f3de25dae4d526bff6902e93b309f298d54900a69 125e0c5ed86e4e881317bf567ad40806d3d2364e793e23f5337 fcb076ce5b434a756483be9b3e8",

"expire_token": "51ce10b8b4cd93b3688ae70ac851def2a108d27dc001184056

– 18 –


233c42a52e76360587d6c80adcf8d3533fe45c89fd622fa556d bf5037b43fd2663dfd4749fc357",

"expire_date": 1707909304, "user": {

"user_id": "57959bf4-ab08-4044-9555- ad6389d566a2",

"user_type": "CLIENT", "first_name": null, "last_name": null, "middle_name": null, "email": "ada26a7a-a495-421c-

[email protected]", "company_id": "d85ddf44-72eb-467f-

a4a6-77872babcace", "is_admin": false, "is_service": true

} }

6.2. Users, companies, user roles

6.2.1. Retrieving a general list of user profiles Address: users/

HTTP method: GET

Purpose: Allows to get a full list of created user profiles.

Response format: List of User entities with paging.

Access control: Users can only see users from their company.

6.2.2. Creating a user account Address: users/

HTTP method: POST

Purpose: Allows to create a new user in the system. Request

format: Data dictionary with the following keys:

● credentials - A dictionary with users’ email and password attributes

– 19 –


● profile - A dictionary where dictionary key is name of an attribute to be set up for the user being created, and values are this attribute respective values

Access control: Only administrators have the privilege to create users. Company administrators are not allowed to create users with a system role or assign a different company to a user (set for company_id attribute a different from their own company).

Response format: created User entity

HTTP status code at successful processing: 201 6.2.2.1. Example: Creating a company user account

POST /api/users/ HTTP/1.1 Host: localhost:8000 X-Forensic-Access-Token: 97b8dd0519f15518386dd60a02f411c06290388f450d17452f5 a56829862658d08b3a93e5315ea1843d7a660e927f8fdc6052f e019b491707babbac9920bf6e3 Content-Type: application/json cache-control: no-cache { "credentials": { "email": "[email protected]", "password": "john_password" }, "profile": { "company_id": "d85ddf44-72eb-467f-

a4a6-77872babcace", "user_type": "CLIENT", "first_name": "john", "last_name": "doe", "middle_name": "", "is_admin": false, "is_service": false }

}

Response: {

"user_id": "68707683- d180-426c-8c1f-6c92ae1b419c",

"user_type": "CLIENT", "first_name": "john", "last_name": "doe",

– 20 –


"middle_name": "", "email": "[email protected]", "company_id": "d85ddf44-72eb-467f-

a4a6-77872babcace", "is_admin": false, "is_service": false

}

6.2.2.2. Example: Creating a company administrator account POST /api/users/ HTTP/1.1 Host: localhost:8000 X-Forensic-Access-Token: ceb28dd97c18a4d839ec013c30736057f51375beba64c5ff8f0 822047f9dcaf6b6afd0227936bb166ee9bce41c374860a0b35f 40f3b398a1ed34741c24d1bf9a Content-Type: application/json cache-control: no-cache Postman-Token: 484a087a-513d-4b4a-a828-3a84ade21ecd { "credentials": { "email": "[email protected]", "password": "john_password" }, "profile": { "user_type": "CLIENT", "first_name": "john", "last_name": "doe", "middle_name": "", "is_admin": true, "company_id": "d85ddf44-72eb-467f-

a4a6-77872babcace" }

}

Response: { "user_id":

"f72de16d-32e0-49a1-9f77-4224b0e4c87d", "user_type": "CLIENT", "first_name": "john", "last_name": "doe", "middle_name": "", "email": "[email protected]", "company_id": "d85ddf44-72eb-467f-

a4a6-77872babcace", "is_admin": true, "is_service": false

}

– 21 –




6.2.3. Retrieving information about a particular user Address: users/{{user_id}}

HTTP method: GET

Purpose: Allows to retrieve information concerning a particular user

Access control: Company users are allowed to get information only about users from their own company

Response format: User entity

HTTP status code at successful processing: 200 6.2.4. Editing a user profile

Address: users/{{user_id}}

HTTP method: PATCH

Purpose: Allows to edit user profile attributes and set a new password.

Request format: A dictionary where dictionary keys are names of a User entity attributes to be edited; also the key:

● password allows to change the user’s password.

Access control: Users are allowed to edit their name component attributes (first_name, last_name, middle_name) and change the password.

A company administrator has the right to change user’s email and is_admin flag.

Response format: User entity

HTTP status code at successful processing: 200 6.2.5. Deleting a user

Address: users/{{user_id}}

HTTP method: DELETE

– 22 –

Purpose: Allows to delete a user.

Access control:

Only administrators have the right to delete users;

company administrators are allowed to delete users from their own company only.

Response format: No response body

HTTP status code at successful processing: 204 6.2.6. Retrieving a general list of

companies Address: companies/

HTTP method: GET

Purpose: Allows to get a full list of companies.

Access control: Company users can only see their companies.

Response format: List of Company entities with paging. 6.2.7. Creating a company profile

Address: companies/

HTTP method: POST

Purpose: Allows to create a new company.

Request format: Data dictionary with the following

key:

● name - company name

Access control: System administrator only. Response format: created

Company entity

HTTP status code at successful processing: 201 6.2.8. Retrieving information about a particular

company Address: users/{{company_id}}

HTTP method: GET – 23 –

Purpose: Allows to retrieve information concerning a particular company

Access control: Company users are allowed to get information about their company only.

Response format: Company entity

HTTP status code at successful processing: 200 6.2.9. Editing a company profile

Address: companies/{{company_id}}

HTTP method: PATCH

Purpose: Allows to edit the value of the company’s name attribute.

Request format: Data dictionary with the following key:

● name - new company name

Access control: Accessible to administrators; company administrators are allowed to edit only their company profile.

Response format: Company entity

HTTP status code at successful processing: 200 6.2.10. Deleting a company

Address:

companies/{{company_id}}

HTTP method: DELETE

Purpose: Allows to delete a company

Access control: Available to the system administrator only.



– 24 –

6.3. Folders 6.3.1. Model

Folders represent the upper level of data abstraction in the system and allow to group multiple images into a single logical business unit.

Typical examples of use:

! A group of a single physical person images to be reviewed with the system

! A group of images from a single car inspection report for a car insurance scenario

! Etc.

Following upper level attributes exist for each folder:

! time_created – date of creating in unix timestamp format

! time_updated – date of last update in unix timestamp format

! meta_data – metadata: an arbitrary JSON data dictionary (intended to attribute folders with data from a partner system)

! folder_id – unique identifier of folder

! resolution_status – status of resolution for the folder with regard to the last activated analyzers’ scope:

o INITIAL – Initial status

o PROCESSING – Analyzers are processing data

o FAILED – A technical or logical failure occurred during the analyzers’ work

o FINISHED – Data processing is finished

o DECLINED – A negative resolution is taken for the folder (images or metadata don’t match the quality criteria)

– 25 –

o SUCCESS – A positive resolution is taken for the folder

! resolution_comment – A system’s or operator’s comment on the accepted folder status

! resolution_time – date of resolution in unix timestamp format

! resolution_endpoint – callback point (URL) on the partner side where results should be sent when the folder status changes

! media – array of media files (images and videos) in the folder

6.3.2. Retrieving a general list of folders Address: folders/

HTTP method: GET

Purpose: Allows to get a complete list of folders previously uploaded to the server

Response format: A list of Folder entities with paging (paging was introduced because very many folders can be stored on the server); folders are arranged from the latest to the earliest

Parameters:

! Paging management

o limit – width of paging selection field (max. value 5000, default value 100)

o offset – offset from top for paging selection (default value 0)

! Filters:

o time_created – exact match of folder creation time

o time_created.max – upper limit for the folder creation time stamp

– 26 –

o time_created.min – lower limit for the folder creation time stamp

o time_updated – exact match of folder update time

o time_updated.max – upper limit for the folder update time stamp

o time_updated.min – lower limit for the folder update time stamp

o resolution_status – filtering by folder status

o resolution_time – exact match of resolution time

o resolution_time.max – upper limit for the resolution time stamp

o resolution_time.min – lower limit for the resolution taking time stamp

o resolution_comment – full text search in the comment

o meta_data – filtering by metadata content, for this purpose:

▪ rules are separated by commas and interpreted as AND

▪ dot notation is used to specify an internal path in metadata

▪ functors == and != can be used for comparison

▪ null is a designated value and can be interpreted as either an empty field value in metadata or absence of a field

Example:

?meta_data=familyname==Ullon,givenname!=Tamara Milagros,address.postalcode!=null


– 27 –

Example: Request: GET /api/folders/ HTTP/1.1 Host: dev.oz-services.ru X-Forensic-Access-Token: 3f9cab9923e91183ab75fe574db76559ecbdb580cec0aa15881 77647f0b9c69865b5f17823ee98ccb6762b3f477f59d9e26fea ce2b71d157f3c4c18a611b8a6a

Response: {

"offset": 0, "limit": 1, "total_count": 59182, "items": [

{ "time_created": 1527754531, "time_updated": 1527758929, "meta_data": {

"email": "[email protected]", "gender": "Male", "address": {

"postalcode": "00000", "addressregion": "PY", "streetaddress": "Demostenes y

Santo Tomas",

Lorenzo"

"addresslocality": "San

}, "birthdate": "2018-04-19", "givenname": "John", "telephone": "+12223334455", "familyname": "Doe", "nationality": "US", "additionalname": "Jameson"

}, "folder_id":

"a215ba29-36c8-4f42-99bd-3e334e3afdb8", "resolution_status": "SUCCESS", "resolution_comment": "Status SUCCESS -

all images processed well", "resolution_time": 1527758929, "resolution_endpoint": "http://

localhost:8000/test/", "resolution_state_hash":

"cca576b032c2c73c", "media": [

{ "time_created": 1549442174,

– 28 –


"time_updated": 1549442174, "meta_data": {}, "media_id":

"c9353b8c-42d3-4cbd-9b5d-85a4197e6113", "media_type": "IMAGE_FOLDER", "info": {

"thumb": { "md5":

"b78b6363923c1f688bc935bf83d40c5f", "size": 3477, "width": 69, "height": 100

}, "original": {

"md5": "24e164069e45ea464004aa818f627e24",

"size": 41535, "width": 270, "height": 388

} }, "tags": [], "original_name": "2.jpg", "image_id":

"c9353b8c-42d3-4cbd-9b5d-85a4197e6113", "original_url": "http://

localhost:8000/static/92ed6be8-1e73-428c-acd4- d0885b5cd8d5/ c9353b8c-42d3-4cbd-9b5d-85a4197e6113.jpeg",

"thumb_url": "http://localhost: 8000/static/92ed6be8-1e73-428c-acd4-d0885b5cd8d5/ c9353b8c-42d3-4cbd-9b5d-85a4197e6113_thumb.jpeg"

}, {

"time_created": 1549442174, "time_updated": 1549442174, "meta_data": {}, "media_id":

"2e49cb18-63ab-4fec-bd25-00a23f60bdcb", "media_type": "IMAGE_FOLDER", "info": {

"thumb": { "md5":

"2e771a4d3284e1b2c936567344eb8d72", "size": 3546, "width": 100, "height": 88

}, "original": {

– 29 –

http://localhost/

"md5": "83881835308e811649d938b018e061ba",



"2e49cb18-63ab-4fec-bd25-00a23f60bdcb", "original_url": "http://

localhost:8000/static/92ed6be8-1e73-428c-acd4- d0885b5cd8d5/2e49cb18-63ab-4fec- bd25-00a23f60bdcb.jpeg",

"thumb_url": "http://localhost: 8000/static/92ed6be8-1e73-428c-acd4- d0885b5cd8d5/2e49cb18-63ab-4fec- bd25-00a23f60bdcb_thumb.jpeg"

}, {


"e103f106-0307-45c7-bfc4-829b35a73c15", "media_type": "VIDEO_FOLDER", "info": {

"thumb": { "md5":

"1e9ceaa431d91ce4272bd921dbc1cef9", "size": 7410, "width": 480, "height": 270

}, "video": {

"FPS": 30, "md5":

"d9061d3da8601932e98f79ec8ba1c877", "size": 1570024, "width": 480, "height": 270, "duration": 30.53

} }, "tags": [], "original_name":

"file_example_MP4_480_1_5MG.mp4", "video_id":

"e103f106-0307-45c7-bfc4-829b35a73c15",

– 30 –

http://localhost/

"video_url": "http://localhost: 8000/static/92ed6be8-1e73-428c-acd4-d0885b5cd8d5/ e103f106-0307-45c7-bfc4-829b35a73c15.mp4",

"thumb_url": "http://localhost: 8000/static/92ed6be8-1e73-428c-acd4-d0885b5cd8d5/ e103f106-0307-45c7-bfc4-829b35a73c15_thumb.jpg"

} ]

} ]

}

6.3.3. Creating a new folder with media data Address: folders/

HTTP method: POST

Purpose: Allows to upload to the server a new folder with images and/or videos

Remarks:

! Format of request body transmission must be multipart/form-data

! Images and videos must be uploaded as the form part FILES, their original names are saved to the server in the field original_name for media files.

! When you create a folder you can define metadata both for the folder and uploaded media files in a single step. To this end JSON-serialized data should be transferred via payload key of a form. Format of payload value data dictionary:

o ‘meta_data’ key – value: an arbitrary metadata dictionary to be set for the folder

o ‘media_meta_data’ key – value: a data dictionary

▪ with the file name as key (FILES) and an arbitrary metadata dictionary to be set for the media file with this name as value

Response format: created Folder entity

– 31 –

http://localhost/

http://localhost/


Example: Request: POST /api/folders/ HTTP/1.1 Host: dev.oz-services.ru X-Forensic-Access-Token: 3f9cab9923e91183ab75fe574db76559ecbdb580cec0aa15881 77647f0b9c69865b5f17823ee98ccb6762b3f477f59d9e26fea ce2b71d157f3c4c18a611b8a6a Content-Type: multipart/form-data; boundary=---- WebKitFormBoundary7MA4YWxkTrZu0gW

----WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="photo1.jpg"; filename="/images/40.jpg

Content-Disposition: form-data; name="photo2.jpg"; filename="/159-P-classic.jpg

Content-Disposition: form-data; name="video1.mp4"; filename="/file_example_MP4_480_1_5MG.mp4

----WebKitFormBoundary7MA4YWxkTrZu0gW

Response: {

"time_created": 1549526394, "time_updated": 1549526394, "meta_data": {}, "folder_id": "8cb409d1-1d2c-4cd4-

aaa5-9b0fda9e7aed", "resolution_time": null, "resolution_status": "INITIAL", "resolution_endpoint": null, "resolution_state_hash": "05115087375fbc64", "resolution_comment": null, "resolution_suggest": null, "archive": false, "media": [

{ "time_created": 1549526394, "time_updated": 1549526394,

– 32 –

"meta_data": {}, "media_id": "c9af63a2-8e7e-4082-

b554-6ef5902ce22c", "media_type": "IMAGE_FOLDER", "info": {

"thumb": { "md5":

"cc0719784a0843d17caffc546b56a919", "size": 4118, "width": 75, "height": 100

}, "original": {

"md5": "354993ac5d9b50abcf4a9bd8e6f36bc8",


} }, "tags": [], "original_name": "159-P-classic.jpg", "image_id": "c9af63a2-8e7e-4082-

b554-6ef5902ce22c", "original_url": "http://127.0.0.1:8080/

static/8cb409d1-1d2c-4cd4-aaa5-9b0fda9e7aed/ c9af63a2-8e7e-4082-b554-6ef5902ce22c.jpeg",

"thumb_url": "http://127.0.0.1:8080/ static/8cb409d1-1d2c-4cd4-aaa5-9b0fda9e7aed/ c9af63a2-8e7e-4082-b554-6ef5902ce22c_thumb.jpeg"

}, {

"time_created": 1549526394, "time_updated": 1549526394, "meta_data": {}, "media_id": "047e422d-43cf-4c60-9b28-

f091f16553f9", "media_type": "IMAGE_FOLDER", "info": {

"thumb": { "md5":


}, "original": {

"md5": "83881835308e811649d938b018e061ba",

"size": 52340,

– 33 –

"width": 604, "height": 533

} }, "tags": [], "original_name": "40.jpg", "image_id": "047e422d-43cf-4c60-9b28-

f091f16553f9", "original_url": "http://127.0.0.1:8080/

static/8cb409d1-1d2c-4cd4-aaa5-9b0fda9e7aed/ 047e422d-43cf-4c60-9b28-f091f16553f9.jpeg",

"thumb_url": "http://127.0.0.1:8080/ static/8cb409d1-1d2c-4cd4-aaa5-9b0fda9e7aed/ 047e422d-43cf-4c60-9b28-f091f16553f9_thumb.jpeg"

}, {


"a50a42c5-81d5-459e-96b2-61e8f79a547b", "media_type": "VIDEO_FOLDER", "info": {

"thumb": { "md5":

"33eb3c572c919802de3b3cdfdfe73779", "size": 7740, "width": 480, "height": 270

}, "video": {

"FPS": 30, "md5":




"a50a42c5-81d5-459e-96b2-61e8f79a547b", "video_url": "http://127.0.0.1:8080/

static/8cb409d1-1d2c-4cd4-aaa5-9b0fda9e7aed/ a50a42c5-81d5-459e-96b2-61e8f79a547b.mp4",

– 34 –

"thumb_url": "http://127.0.0.1:8080/ static/8cb409d1-1d2c-4cd4-aaa5-9b0fda9e7aed/ a50a42c5-81d5-459e-96b2-61e8f79a547b_thumb.jpg"

} ]

}

6.3.4. Retrieving information about a particular folder Address: folders/{{folder_id}}

HTTP method: GET

Purpose: Allows to retrieve information concerning a particular folder

Response format: Folder entity


Example: Request: GET /api/folders/ 1c806b41-2588-44c3-9b2b-2001fe8b610b HTTP/1.1 Host: dev.oz-services.ru X-Forensic-Access-Token: 3f9cab9923e91183ab75fe574db76559ecbdb580cec0aa15881 77647f0b9c69865b5f17823ee98ccb6762b3f477f59d9e26fea ce2b71d157f3c4c18a611b8a6a

Response: {

"time_created": 1528966319, "time_updated": 1528966319, "meta_data": {}, "folder_id":

"1c806b41-2588-44c3-9b2b-2001fe8b610b", "resolution_status": "INITIAL", "resolution_comment": null, "resolution_time": null, "resolution_endpoint": null, "resolution_state_hash": "99ededfb37bddce6", archive": false, "media": [

{ "time_created": 1549526394, "time_updated": 1549526394, "meta_data": {}, "media_id": "c9af63a2-8e7e-4082-

b554-6ef5902ce22c",

– 35 –

"media_type": "IMAGE_FOLDER", "info": {

"thumb": { "md5":


}, "original": {







}, {



"thumb": { "md5":


}, "original": {

"md5": "83881835308e811649d938b018e061ba",


}

– 36 –

}, "tags": [], "original_name": "40.jpg", "image_id": "047e422d-43cf-4c60-9b28-




}, {



"thumb": { "md5":


}, "video": {

"FPS": 30, "md5":







} ]

– 37 –

}

6.3.5. Editing folder data Address: folders/{{folder_id}}

HTTP method: PATCH

Purpose: Allows to edit certain fields of a folder, namely:

! resolution_endpoint – callback service address

! resolution_comment – comment about the resolution (should not be available to a partner's call)

! resolution_status – resolution status (should not be available to a partner's call)

Response format: Folder entity


Example: Request: PATCH /api/folders/ 1c806b41-2588-44c3-9b2b-2001fe8b610b/ HTTP/1.1 Host: localhost:8000 X-Forensic-Access-Token: 3f9cab9923e91183ab75fe574db76559ecbdb580cec0aa15881 77647f0b9c69865b5f17823ee98ccb6762b3f477f59d9e26fea ce2b71d157f3c4c18a611b8a6a Content-Type: application/json Cache-Control: no-cache Postman-Token: 7e517c4e-9aa4-4669-bd3b-50f3b2f5e065

{ "resolution_endpoint": "http://some-server.com/

folder_callback/", "resolution_comment": "Status SUCCESS - all

images processed well", "resolution_status": "SUCCESS"

}

Response: {

"time_created": 1528966319, "time_updated": 1528967596, "meta_data": {},

– 38 –

http://some-server.com/

"folder_id": "1c806b41-2588-44c3-9b2b-2001fe8b610b",

"resolution_status": "SUCCESS", "resolution_comment": "Status SUCCESS - all

images processed well", "resolution_time": 1528967596, "resolution_endpoint": "http://some-server.com/

folder_callback/", "resolution_state_hash": "12cdbcd6277bb405", archive": false, "media": [

{ "time_created": 1549526394, "time_updated": 1549526394, "meta_data": {}, "media_id": "c9af63a2-8e7e-4082-


"thumb": { "md5":


}, "original": {







}, {


– 39 –

http://some-server.com/

"media_id": "047e422d-43cf-4c60-9b28- f091f16553f9",

"media_type": "IMAGE_FOLDER", "info": {

"thumb": { "md5":


}, "original": {

"md5": "83881835308e811649d938b018e061ba",






}, {



"thumb": { "md5":


}, "video": {

"FPS": 30, "md5":

"d9061d3da8601932e98f79ec8ba1c877", "size": 1570024,

– 40 –

"width": 480, "height": 270, "duration": 30.53






} ]

}

6.3.6. Deleting folders Address: folders/{{folder_id}}

HTTP method: DELETE

Purpose: Allows to delete a folder



Example: Request: DELETE /api/folders/ 1c806b41-2588-44c3-9b2b-2001fe8b610b/ HTTP/1.1 Host: localhost:8000 X-Forensic-Access-Token: 3f9cab9923e91183ab75fe574db76559ecbdb580cec0aa15881 77647f0b9c69865b5f17823ee98ccb6762b3f477f59d9e26fea ce2b71d157f3c4c18a611b8a6a Cache-Control: no-cache Postman-Token: 2465c103-6f7f-4a23-9a6d-16c1dd90ff8b

Response: ---

– 41 –

6.4. Media files 6.4.1. Model 6.4.1.1. Images

Each image is described in a generic form by the following set of basic attributes:

! media_type – type of media data, IMAGE_FOLDER



! meta_data – metadata, an arbitrary JSON data dictionary

! media_id – unique identifier of image

! original_url – link to a full resolution image file

! thumb_url – link to a thumb of an image

! original_name – original name of an uploaded file. Some image types

may have additional attributes which are defined below.

6.4.1.2. Videos

Videos are described with the following set of attributes:

! media_type – type of media data, VIDEO_FOLDER ● time_created – date of creating in unix timestamp format ● time_updated – date of last update in unix timestamp format ● meta_data – metadata, an arbitrary JSON data dictionary ● media_id – unique identifier of video file ● video_url – link to an uploaded video file ● thumb_url – link to a preview of a video file

● original_name – original name of an uploaded file

– 42 –

6.4.2. Retrieving a list of media files in folder Address: folders/{{folder_id}}/media/

HTTP method: GET

Purpose: Allows to retrieve information about images in a particular folder

Response format: array of Image and Video entities


Example: Request GET /api/folders/33c727a1-3652-4646- a6eb-7dec394243e9/media/ HTTP/1.1 Host: dev.oz-services.ru X-Forensic-Access-Token: 3f9cab9923e91183ab75fe574db76559ecbdb580cec0aa15881 77647f0b9c69865b5f17823ee98ccb6762b3f477f59d9e26fea ce2b71d157f3c4c18a611b8a6a Cache-Control: no-cache

Response: [

{ "time_created": 1549526394, "time_updated": 1549526394, "meta_data": {}, "media_id": "047e422d-43cf-4c60-9b28-


"thumb": { "md5":


}, "original": {

"md5": "83881835308e811649d938b018e061ba",


} },

– 43 –

"tags": [], "original_name": "40.jpg", "image_id": "047e422d-43cf-4c60-9b28-



"thumb_url": "http://127.0.0.1:8080/static/ 8cb409d1-1d2c-4cd4-aaa5-9b0fda9e7aed/ 047e422d-43cf-4c60-9b28-f091f16553f9_thumb.jpeg"

}, {

"time_created": 1549526394, "time_updated": 1549526394, "meta_data": {}, "media_id": "c9af63a2-8e7e-4082-


"thumb": { "md5":


}, "original": {






"thumb_url": "http://127.0.0.1:8080/static/ 8cb409d1-1d2c-4cd4-aaa5-9b0fda9e7aed/ c9af63a2-8e7e-4082-b554-6ef5902ce22c_thumb.jpeg"

}, {


– 44 –

"media_id": "a50a42c5-81d5-459e-96b2-61e8f79a547b",

"media_type": "VIDEO_FOLDER", "info": {

"thumb": { "md5":


}, "video": {

"FPS": 30, "md5":




"a50a42c5-81d5-459e-96b2-61e8f79a547b", "video_url": "http://127.0.0.1:8080/static/

8cb409d1-1d2c-4cd4-aaa5-9b0fda9e7aed/ a50a42c5-81d5-459e-96b2-61e8f79a547b.mp4",

"thumb_url": "http://127.0.0.1:8080/static/ 8cb409d1-1d2c-4cd4-aaa5-9b0fda9e7aed/ a50a42c5-81d5-459e-96b2-61e8f79a547b_thumb.jpg"

} ]

6.4.3. Adding media files to folder Address: folders/{{folder_id}}/media/

HTTP method: POST

Purpose: Allows to add an image or a video (or multiple media filed) into a folder

Remarks:

! Format of request body transmission must be multipart/form-data

– 45 –

! Media files must be uploaded as the form part FILES, their original names are saved to the server in the field original_name for media files.

Response format: array of Image and Video entities


Example: POST /api/folders/8cb409d1-1d2c-4cd4- aaa5-9b0fda9e7aed/media/ HTTP/1.1 Host: localhost:8000 X-Forensic-Access-Token: 0fe98b4135bca617ea5b287a48d51a895191c0357de6bd55f67 5f0413cc251b4f1f1e4bb2ca2230d9c13817fec0ddfa773d7c8 84049fdab7a8f48295f5d1159b cache-control: no-cache Postman-Token: 73ca8b45-145e-427b-bc2e-f7b8d91dae30 Content-Type: multipart/form-data; boundary=---- WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="image1"; filename="/images/40.jpg

Content-Disposition: form-data; name="video1"; filename="/static/file_example_MP4_480_1_5MG.mp4

------WebKitFormBoundary7MA4YWxkTrZu0gW--

Response: [

{ "time_created": 1549528232, "time_updated": 1549528232, "meta_data": {}, "media_id": "eb4a3c79-1375-4908-8148-

b1c79df005e5", "media_type": "IMAGE_FOLDER", "info": {

"thumb": { "md5":


– 46 –

}, "original": {

"md5": "83881835308e811649d938b018e061ba",


} }, "tags": [], "original_name": "40.jpg", "image_id": "eb4a3c79-1375-4908-8148-

b1c79df005e5", "original_url": "http://127.0.0.1:8080/

static/8cb409d1-1d2c-4cd4-aaa5-9b0fda9e7aed/ eb4a3c79-1375-4908-8148-b1c79df005e5.jpeg",

"thumb_url": "http://127.0.0.1:8080/static/ 8cb409d1-1d2c-4cd4-aaa5-9b0fda9e7aed/ eb4a3c79-1375-4908-8148-b1c79df005e5_thumb.jpeg"

}, {

"time_created": 1549528232, "time_updated": 1549528232, "meta_data": {}, "media_id": "a3e30d9c-9406-4441-92c5-

a0db99092d99", "media_type": "VIDEO_FOLDER", "info": {

"thumb": { "md5":

"a5c0d267a4b8f22a5f3b4da070869899", "size": 6491, "width": 480, "height": 270

}, "video": {

"FPS": 30, "md5":



"file_example_MP4_480_1_5MG.mp4", "video_id": "a3e30d9c-9406-4441-92c5-

a0db99092d99",

– 47 –

"video_url": "http://127.0.0.1:8080/static/ 8cb409d1-1d2c-4cd4-aaa5-9b0fda9e7aed/ a3e30d9c-9406-4441-92c5-a0db99092d99.mp4",

"thumb_url": "http://127.0.0.1:8080/static/ 8cb409d1-1d2c-4cd4-aaa5-9b0fda9e7aed/ a3e30d9c-9406-4441-92c5-a0db99092d99_thumb.jpg"

} ]

6.4.4. Deleting media files from folder Address:

folders/{{folder_id}}/media/{{media_id}}

HTTP method: DELETE

Purpose: Allows to delete a media file from a folder

Response format: Empty response body


Example: Request DELETE /api/folders/33c727a1-3652-4646- a6eb-7dec394243e9/media/ 99da5e30-9fb1-44d5-9083-10f553199f09 HTTP/1.1 Host: dev.oz-services.ru X-Forensic-Access-Token: 3f9cab9923e91183ab75fe574db76559ecbdb580cec0aa15881 77647f0b9c69865b5f17823ee98ccb6762b3f477f59d9e26fea ce2b71d157f3c4c18a611b8a6a Cache-Control: no-cache Response: —

6.5. Tagging media files 6.5.1. Overview

Media files support a tagging mechanism: when creating (by POST method) or modifying (by PATCH method) entity data one can assign tags by setting a value for ‘tags’ query field. Value of the ‘tags’ field is an array of string values of assigned tag identifiers.

– 48 –

6.5.2. Acceptable tags with descriptions

Identifier Description

photo_id ID card image

photo_id_front ID card image (front)

photo_id_back ID card image (back)

photo_bill Image of household register extract

photo_cert Image of investor certificate

photo_selfie Image of the subject

video_selfie This tag is transferred with a video file and means that the subject appears in the video

video_id This tag is transferred with a video file and means that the subject's ID card appears in the video

video_selfie_left This tag should be used only together with video_selfie tag. Head turned to the left.

video_selfie_right This tag should be used only together with video_selfie tag. Head turned

to the right.

video_selfie_down This tag should be used only together with video_selfie tag. Head tilted downwards.

video_selfie_high This tag should be used only together with video_selfie tag. Head raised up.

video_selfie_zoom_in This tag should be used only together with video_selfie tag. Head is moved closer to the camera.

video_selfie_zoom_out This tag should be used only together with video_selfie tag. Head is moved farther from the camera.

– 49 –

video_selfie_smile This tag should be used only together with video_selfie tag. Smile.

video_selfie_eyes This tag should be used only together with video_selfie tag. Eyes shut.

video_id_zoom_show This tag should be used only together with video_id tag. Demonstrating an ID card.

video_id_zoom_in This tag should be used only together with video_id tag. Zooming in the ID card.

video_id_zoom_out This tag should be used only together with video_id tag. Zooming out the ID card.

video_id_horizontal This tag should be used only together with video_id tag. Moving the ID card horizontally.

video_id_vertical This tag should be used only together with video_id tag. Moving the ID card vertically.

6.6. Analyzers

6.6.1. Model

The work process of each analyzer is reflected in Analyse entity which supports following common basic attributes:



! meta_data – metadata, an arbitrary JSON data dictionary

! analyse_id – unique identifier of analysis

– 50 –

! folder_id – unique identifier of parent folder

! type – one of the following analysis types:

o DOCUMENTS

o BIOMETRY

o FORENSIC

o COLLECTION

o KYC

! state – one of the following analysis states:

o PROCESSING – under process

o FAILED – data processing error

o FINISHED – processing finished

! results_data – output meta results of the analyzer work

! error_message – error message

! error_code – error code

! source_media – list of media files for which the analyzer was launched

! results_media – output results for single original media files

! results_group – output results (media files) for the whole list of media files

NB: some analysis types may have an additional list of attributes.

6.6.2. Launch of folder analysis Address:

folders/{{folder_id}}/analyses/ HTTP

method: POST

Purpose: Allows to start an analysis for images in the folder. Following conditions apply:

– 51 –

! Data about which analyzers should be launched are provided under key analyses of the upper level dictionary.

! Each record may contain the following fields:

o type – type of the analyzer to be launched (mandatory)

o meta_data – metadata to be added to the analysis (optional, default value is null)

o source_media – array of identifiers of those media files in the folder for which the analyzer will be launched (optional; by default all files from the folder are analyzed)

o params – special parameters of the analyzer:

▪ Photo expert:

! get_all_results – boolean flag that allows to get results for all or only for incident images

! lang – language locale for comments output (ru/en)

! automated_forgery_flags – set of flags allowing to launch analysis automatically for received images

Response format: array of Analyse entities


Example: Request POST /api/folders/8cb409d1-1d2c-4cd4- aaa5-9b0fda9e7aed/analyses/ HTTP/1.1 Host: localhost:8000 X-Forensic-Access-Token: 0fe98b4135bca617ea5b287a48d51a895191c0357de6bd55f67 5f0413cc251b4f1f1e4bb2ca2230d9c13817fec0ddfa773d7c8 84049fdab7a8f48295f5d1159b Content-Type: application/json

– 52 –

cache-control: no-cache Postman-Token: 08fb99ce-beed-4249-be75-5091322e4faf { "analyses": [ { "type": "documents", "meta_data": { "some_key": "some_value"

}, "source_media": [ "eb4a3c79-1375-4908-8148-b1c79df005e5"

] }, { "type": "biometry", "meta_data": { "some_key": "some_value"

} }, { "type": "forensic", "params": { "get_all_results": false, "lang": "ru", "automated_forgery_flags": [ "DQT_RED", "DQT_ORANGE", "DQT_YELLOW", "DQT_LIAM", "CLONES_RED", "CLONES_ORANGE", "CLONES_YELLOW", "CLONES_LIME"

] }

}, { "type": "kyc", "meta_data": { "some_key": "some_value"

} }, {

"type": "liveness", "meta_data": { "some_key": "some_value"

} }

] }

– 53 –

Response: [


"some_key": "some_value" }, "analyse_id": "1ee3a504-

ba0c-4295-952b-2347d2e8da4b", "folder_id": "8cb409d1-1d2c-4cd4-

aaa5-9b0fda9e7aed", "type": "DOCUMENTS", "state": "PROCESSING", "results_data": null, "error_message": null, "error_code": null, "operator_resolution": null, "source_media": [

{ "time_created": 1549528232, "time_updated": 1549528232, "meta_data": {}, "media_id":

"eb4a3c79-1375-4908-8148-b1c79df005e5", "media_type": "IMAGE_FOLDER", "info": {

"thumb": { "md5":


}, "original": {

"md5": "83881835308e811649d938b018e061ba",



"eb4a3c79-1375-4908-8148-b1c79df005e5", "original_url": "http://

127.0.0.1:8080/static/8cb409d1-1d2c-4cd4-

– 54 –

aaa5-9b0fda9e7aed/eb4a3c79-1375-4908-8148- b1c79df005e5.jpeg",

"thumb_url": "http:// 127.0.0.1:8080/static/8cb409d1-1d2c-4cd4- aaa5-9b0fda9e7aed/eb4a3c79-1375-4908-8148- b1c79df005e5_thumb.jpeg"

} ], "results_media": [

{ "media_association_id": 55, "analyse_id": "1ee3a504-

ba0c-4295-952b-2347d2e8da4b", "results_data": null, "media_association_type": "IMAGE", "source_image_id":

"eb4a3c79-1375-4908-8148-b1c79df005e5", "output_images": []

} ], "results_group": [], "resolution_status": "PROCESSING", "resolution": "PROCESSING"

}, {

"time_created": 1549529193, "time_updated": 1549529193, "meta_data": {

"some_key": "some_value" }, "analyse_id": "45bc82cb-d7d9-4e97-964c-

aa9882d3dd03", "folder_id": "8cb409d1-1d2c-4cd4-

aaa5-9b0fda9e7aed", "type": "BIOMETRY", "state": "PROCESSING", "results_data": null, "error_message": null, "error_code": null, "operator_resolution": null, "source_media": [



"thumb": {

– 55 –

"md5": "2e771a4d3284e1b2c936567344eb8d72",


}, "original": {

"md5": "83881835308e811649d938b018e061ba",




127.0.0.1:8080/static/8cb409d1-1d2c-4cd4- aaa5-9b0fda9e7aed/eb4a3c79-1375-4908-8148- b1c79df005e5.jpeg",


}, {



"thumb": { "md5":


}, "original": {



} },

– 56 –

classic.jpg",

"tags": [], "original_name": "159-P-

"image_id": "c9af63a2-8e7e-4082-

b554-6ef5902ce22c", "original_url": "http://

127.0.0.1:8080/static/8cb409d1-1d2c-4cd4- aaa5-9b0fda9e7aed/c9af63a2-8e7e-4082- b554-6ef5902ce22c.jpeg",

"thumb_url": "http:// 127.0.0.1:8080/static/8cb409d1-1d2c-4cd4- aaa5-9b0fda9e7aed/c9af63a2-8e7e-4082- b554-6ef5902ce22c_thumb.jpeg"

}, {


"047e422d-43cf-4c60-9b28-f091f16553f9", "media_type": "IMAGE_FOLDER", "info": {

"thumb": { "md5":


}, "original": {

"md5": "83881835308e811649d938b018e061ba",



"047e422d-43cf-4c60-9b28-f091f16553f9", "original_url": "http://

127.0.0.1:8080/static/8cb409d1-1d2c-4cd4- aaa5-9b0fda9e7aed/047e422d-43cf-4c60-9b28- f091f16553f9.jpeg",

"thumb_url": "http:// 127.0.0.1:8080/static/8cb409d1-1d2c-4cd4- aaa5-9b0fda9e7aed/047e422d-43cf-4c60-9b28- f091f16553f9_thumb.jpeg"

}

– 57 –

], "results_media": [

{ "media_association_id": 56, "analyse_id": "45bc82cb-

d7d9-4e97-964c-aa9882d3dd03", "results_data": null, "media_association_type": "IMAGE", "source_image_id":


}, {

"media_association_id": 57, "analyse_id": "45bc82cb-


"c9af63a2-8e7e-4082-b554-6ef5902ce22c", "output_images": []

}, {



"047e422d-43cf-4c60-9b28-f091f16553f9", "output_images": []


}, {

"time_created": 1549529193, "time_updated": 1549529193, "meta_data": null, "analyse_id": "74db4748-

d71a-4b16-95fe-97b9c0869925", "folder_id": "8cb409d1-1d2c-4cd4-

aaa5-9b0fda9e7aed", "type": "FORENSIC", "state": "PROCESSING", "results_data": null, "error_message": null, "error_code": null,

– 58 –

"operator_resolution": null, "confs": {

"lang": "ru", "remove_perfect": false, "automated_forgery_flags": [

"DQT_YELLOW", "CLONES_RED", "CLONES_LIME", "DQT_ORANGE", "CLONES_ORANGE", "DQT_LIAM", "CLONES_YELLOW", "DQT_RED"

] }, "source_media": [



"thumb": { "md5":


}, "original": {

"md5": "83881835308e811649d938b018e061ba",





"thumb_url": "http:// 127.0.0.1:8080/static/8cb409d1-1d2c-4cd4-

– 59 –

aaa5-9b0fda9e7aed/eb4a3c79-1375-4908-8148- b1c79df005e5_thumb.jpeg"

}, {



"thumb": { "md5":


}, "original": {



} },

classic.jpg",






}, {



"thumb": {

– 60 –

"md5": "2e771a4d3284e1b2c936567344eb8d72",


}, "original": {

"md5": "83881835308e811649d938b018e061ba",







{ "media_association_id": 59, "analyse_id": "74db4748-

d71a-4b16-95fe-97b9c0869925", "results_data": null, "media_association_type": "IMAGE", "source_image_id":


}, {

"media_association_id": 60, "analyse_id": "74db4748-



}, {

– 61 –





}, {


"some_key": "some_value" }, "analyse_id": "c20a788e-59df-463f-

a33a-19a64c081929", "folder_id": "8cb409d1-1d2c-4cd4-

aaa5-9b0fda9e7aed", "type": "KYC", "state": "PROCESSING", "results_data": null, "error_message": null, "error_code": null, "operator_resolution": null, "source_media": [], "results_media": [], "results_group": [], "resolution_status": "PROCESSING", "resolution": "PROCESSING"

}, {


"some_key": "some_value" }, "analyse_id": "9628a61e-7897-4668-bcef-

c067c3519f7d", "folder_id": "8cb409d1-1d2c-4cd4-

aaa5-9b0fda9e7aed", "type": "LIVENESS", "state": "PROCESSING", "results_data": null, "error_message": null,

– 62 –

"error_code": null, "operator_resolution": null, "source_media": [


"a3e30d9c-9406-4441-92c5-a0db99092d99", "media_type": "VIDEO_FOLDER", "info": {

"thumb": { "md5":

"a5c0d267a4b8f22a5f3b4da070869899", "size": 6491, "width": 480, "height": 270

}, "video": {

"FPS": 30, "md5":




"a3e30d9c-9406-4441-92c5-a0db99092d99", "video_url": "http://

127.0.0.1:8080/static/8cb409d1-1d2c-4cd4- aaa5-9b0fda9e7aed/a3e30d9c-9406-4441-92c5- a0db99092d99.mp4",

"thumb_url": "http:// 127.0.0.1:8080/static/8cb409d1-1d2c-4cd4- aaa5-9b0fda9e7aed/a3e30d9c-9406-4441-92c5- a0db99092d99_thumb.jpg"

}, {



– 63 –

"thumb": { "md5":


}, "video": {

"FPS": 30, "md5":




"a50a42c5-81d5-459e-96b2-61e8f79a547b", "video_url": "http://

127.0.0.1:8080/static/8cb409d1-1d2c-4cd4- aaa5-9b0fda9e7aed/ a50a42c5-81d5-459e-96b2-61e8f79a547b.mp4",

"thumb_url": "http:// 127.0.0.1:8080/static/8cb409d1-1d2c-4cd4- aaa5-9b0fda9e7aed/ a50a42c5-81d5-459e-96b2-61e8f79a547b_thumb.jpg"


{ "media_association_id": 62, "analyse_id": "9628a61e-7897-4668-

bcef-c067c3519f7d", "results_data": null, "media_association_type": "VIDEO", "source_video_id":

"a3e30d9c-9406-4441-92c5-a0db99092d99", "output_images": []

}, {

"media_association_id": 63, "analyse_id": "9628a61e-7897-4668-

bcef-c067c3519f7d", "results_data": null, "media_association_type": "VIDEO",

– 64 –

"source_video_id": "a50a42c5-81d5-459e-96b2-61e8f79a547b",

"output_images": [] }

], "results_group": [], "resolution_status": "PROCESSING", "resolution": "PROCESSING"

} ]

6.6.3. Retrieving analysis results Address: folders/{{folder_id}}/analyses/

HTTP method: GET

Purpose: Allows to retrieve all results of processing a specified folder with analyzers

Response format: array of Analyse entities


Example: Request GET /api/folders/dd729ae5-1d15-478b- ae72-6b52e7b9d812/analyses/ HTTP/1.1 Host: localhost:8000 X-Forensic-Access-Token: 3f9cab9923e91183ab75fe574db76559ecbdb580cec0aa15881 77647f0b9c69865b5f17823ee98ccb6762b3f477f59d9e26fea ce2b71d157f3c4c18a611b8a6a

Response: [


"some_key": "some_value" }, "analyse_id": "45bc82cb-d7d9-4e97-964c-

aa9882d3dd03", "folder_id": "8cb409d1-1d2c-4cd4-

aaa5-9b0fda9e7aed", "type": "BIOMETRY", "state": "PROCESSING",

– 65 –

"results_data": null, "error_message": null, "error_code": null, "operator_resolution": null, "source_media": [



"thumb": { "md5":


}, "original": {

"md5": "83881835308e811649d938b018e061ba",






}, {



"thumb": {

– 66 –

"md5": "cc0719784a0843d17caffc546b56a919",


}, "original": {



} },

classic.jpg",






}, {



"thumb": { "md5":


}, "original": {

"md5": "83881835308e811649d938b018e061ba",


}

– 67 –

}, "tags": [], "original_name": "40.jpg", "image_id":





{ "media_association_id": 56, "analyse_id": "45bc82cb-



}, {




}, {





– 68 –

} ]

6.6.4. Retrieving a particular analysis Address: analyses/{{analyse_id}}

HTTP method: GET

Purpose: Allows to retrieve information concerning a particular analysis

Response format: Analyse entity


Example: Request GET /api/analyses/d5314362-e22a-4a66- a72b-458444974ac9 HTTP/1.1 Host: localhost:8000 X-Forensic-Access-Token: 3f9cab9923e91183ab75fe574db76559ecbdb580cec0aa15881 77647f0b9c69865b5f17823ee98ccb6762b3f477f59d9e26fea ce2b71d157f3c4c18a611b8a6a

Response: {

"time_created": 1549529193, "time_updated": 1549529193, "meta_data": null, "analyse_id": "74db4748-

d71a-4b16-95fe-97b9c0869925", "folder_id": "8cb409d1-1d2c-4cd4-

aaa5-9b0fda9e7aed", "type": "FORENSIC", "state": "PROCESSING", "results_data": null, "error_message": null, "error_code": null, "operator_resolution": null, "confs": {


"DQT_YELLOW", "CLONES_RED", "CLONES_LIME", "DQT_ORANGE", "CLONES_ORANGE", "DQT_LIAM",

– 69 –

"CLONES_YELLOW", "DQT_RED"

] }, "source_media": [

{ "time_created": 1549528232, "time_updated": 1549528232, "meta_data": {}, "media_id": "eb4a3c79-1375-4908-8148-

b1c79df005e5", "media_type": "IMAGE_FOLDER", "info": {

"thumb": { "md5":


}, "original": {

"md5": "83881835308e811649d938b018e061ba",


} }, "tags": [], "original_name": "40.jpg", "image_id": "eb4a3c79-1375-4908-8148-

b1c79df005e5", "original_url": "http://127.0.0.1:8080/

static/8cb409d1-1d2c-4cd4-aaa5-9b0fda9e7aed/ eb4a3c79-1375-4908-8148-b1c79df005e5.jpeg",

"thumb_url": "http://127.0.0.1:8080/ static/8cb409d1-1d2c-4cd4-aaa5-9b0fda9e7aed/ eb4a3c79-1375-4908-8148-b1c79df005e5_thumb.jpeg"

}, {



"thumb": { "md5":

"cc0719784a0843d17caffc546b56a919",

– 70 –


}, "original": {







}, {



"thumb": { "md5":


}, "original": {

"md5": "83881835308e811649d938b018e061ba",



f091f16553f9",

– 71 –

"original_url": "http://127.0.0.1:8080/ static/8cb409d1-1d2c-4cd4-aaa5-9b0fda9e7aed/ 047e422d-43cf-4c60-9b28-f091f16553f9.jpeg",



{ "media_association_id": 59, "analyse_id": "74db4748-



}, {


d71a-4b16-95fe-97b9c0869925", "results_data": null, "media_association_type": "IMAGE", "source_image_id": "c9af63a2-8e7e-4082-

b554-6ef5902ce22c", "output_images": []

}, {





}

6.6.5. Deleting an analysis Address: analyses/{{analyse_id}}

– 72 –

HTTP method: DELETE

Purpose: Allows to delete an analysis from the system

Response format: Empty response body


Example: Request DELETE /api/analyses/d5314362-e22a-4a66- a72b-458444974ac9 HTTP/1.1 Host: localhost:8000 X-Forensic-Access-Token: 3f9cab9923e91183ab75fe574db76559ecbdb580cec0aa15881 77647f0b9c69865b5f17823ee98ccb6762b3f477f59d9e26fea ce2b71d157f3c4c18a611b8a6a

Response: ---

6.6. Metadata

All upper level entities (folders, images, analyses) allow to add/delete/edit linked metadata in form of an arbitrary JSON data dictionary.

Below you will find examples of editing metadata for analyses. 6.6.1. Retrieving metadata

Address: analyses/{{analyse_id}}/meta_data

HTTP method: GET

Purpose: Allows to get analysis metadata; if no metadata are provided, fixed string “null” will be returned.

Response format: arbitrary dictionary


Example: Request GET /api/analyses/d5314362-e22a-4a66- a72b-458444974ac9/meta_data HTTP/1.1 Host: localhost:8000

– 73 –

X-Forensic-Access-Token: 3f9cab9923e91183ab75fe574db76559ecbdb580cec0aa15881 77647f0b9c69865b5f17823ee98ccb6762b3f477f59d9e26fea ce2b71d157f3c4c18a611b8a6a

Response: {

"some_key": "some_value" }

6.6.2. Setting up metadata Address: analyses/{{analyse_id}}/meta_data

HTTP method: POST

Purpose: Allows to replace all analysis metadata (a correct JSON dictionary must be submitted as input data)



Example: Request POST /api/analyses/61743872- ac06-4ccb-8d16-96b59d1d0215/meta_data HTTP/1.1 Host: localhost:8000 X-Forensic-Access-Token: 3f9cab9923e91183ab75fe574db76559ecbdb580cec0aa15881 77647f0b9c69865b5f17823ee98ccb6762b3f477f59d9e26fea ce2b71d157f3c4c18a611b8a6a Content-Type: application/json Cache-Control: no-cache Postman-Token: 4793296e-8970-4e2e-8de8-e57c342ea696

{ "key_4": { "sub_key_2": "sub_value_2", "sub_key_1": "sub_value_1"

}, "key_1": "value_1", "key_3": [ 1, 2, 3, 4

], "key_2": "value_2"

– 74 –

} Response: {

"key_1": "value_1", "key_2": "value_2", "key_3": [

1, 2, 3, 4

], "key_4": {

"sub_key_1": "sub_value_1", "sub_key_2": "sub_value_2"

} }

6.6.3. Editing metadata Address: analyses/{{analyse_id}}/meta_data

HTTP method: PATCH

Purpose: Allows to update analysis metadata by merging existing metadata with a dictionary submitted as input data



Example: Request PATCH /api/analyses/61743872- ac06-4ccb-8d16-96b59d1d0215/meta_data HTTP/1.1 Host: localhost:8000 X-Forensic-Access-Token: 3f9cab9923e91183ab75fe574db76559ecbdb580cec0aa15881 77647f0b9c69865b5f17823ee98ccb6762b3f477f59d9e26fea ce2b71d157f3c4c18a611b8a6a Content-Type: application/json Cache-Control: no-cache Postman-Token: db8d64c5-d643-4905-972c-61d169d2671d

{ "key_5": "appended_value_5", "key_2": "modified_value_2"

}

Response:

– 75 –

{ "key_1": "value_1", "key_2": "modified_value_2", "key_3": [

1, 2, 3, 4

], "key_4": {

"sub_key_1": "sub_value_1", "sub_key_2": "sub_value_2"

}, "key_5": "appended_value_5"

}

6.6.4. Clearing metadata Address: analyses/{{analyse_id}}/meta_data

HTTP method: DELETE

Purpose: Allows to clear delete all analysis metadata



Example: Request DELETE /api/analyses/61743872- ac06-4ccb-8d16-96b59d1d0215/meta_data HTTP/1.1 Host: localhost:8000 X-Forensic-Access-Token: 3f9cab9923e91183ab75fe574db76559ecbdb580cec0aa15881 77647f0b9c69865b5f17823ee98ccb6762b3f477f59d9e26fea ce2b71d157f3c4c18a611b8a6a

Response: ---

– 76 –

Specifications of analyzers 7. Basic error codes

Various errors may be generated during processing with analyzers. Base codes of such errors are as follows:

! 200 – Unknown error

! 201 – Net request failed (e. g. maximum document size for this type of analysis exceeded)

! 202 – Inappropriate image (e. g. in case of document analysis this error may be generated if no document can be detected or unambiguously identified in an image)

! 203 – Image processing error (e. g. in case of document analysis this error may be generated if text fields in an identified document image can’t be read)

! 204 – Technical expiry of allowable data processing time (e.g. as a result of connection break between API head-end and the actual processing server of the respective analyzer)

! 205 – Inadmissible analyzer (e.g. if a specified type of image analysis is not supported for the target server)

! 206 – Logical expiry of allowable data processing time when a remote analyzer machine responds correctly but is not ready to provide data processing results (e.g. In case of analyzer failure and generating an endless loop of repeating data processing attempts)

– 77 –

! 300 – External interruption (e.g. if the analyzer’s work or a more general folder processing are interrupted by an external command like analyzer restart or taking decisions for the folder)

8. KYC check service 8.1. Input

This analyzer does not use any images from the folder for processing, so it ignores source_media parameter when an analysis is generated. Only metadata of the folder for which the analyzer is started are considered. At that following fields are analyzed and interpreted:

! email – e-mail address (mandatory for a correct launch of the analyzer)

! address

o postalcode - postal code

o streetaddress – street and house number

o addresscountry – country as a two digit Alpha code

o addresslocality - city/town

! birthdate – date of birth

! givenname – first name

! familyname – surname

! nationality – nationality as a two digit Alpha code "meta_data": {

Santo Tomas",

"email": "[email protected]", "address": {

"postalcode": "00000", "streetaddress": "Demostenes y

"addresscountry": "PY",

– 78 –


Lorenzo"

"addresslocality": "San

},

}

8.2. Output

"birthdate": "2018-04-19", "givenname": "Rudi", "familyname": "Ullon", "nationality": "PY"

KYC analysis answer is stored in results_data for the analysis and is arranged as follows:

! score – points scored

! rec_4stop – conclusion recommended by 4stop API.Options: "Reject", "Approve", "Review"

! rec_result – conclusion recommended by our businesses logic. Options: "Reject", "Approve", "Review"

! rec_category – identified matches with external databases. Following data are provided for each match:

o name - name

o source – data source, e.g. the provider that found this match (see detailed information below)

o type – match type

o is_san – boolean flag indicating that the person was found in a sanctions database

Example: "rec_category": [

{ "name": "Compliance : CW: Politically Exposed

Person - PEP (Extra as Country Matches)", "source": "CW1", "type": "Politically Exposed Person", "is_san": false

}, { "name": "Compliance : CW: Politically Exposed

Person - PEP", "source": "CW1",

– 79 –

"type": "Politically Exposed Person", "is_san": false

} ]

! coincidence – identified birth date and country coincidences Example: "coincidence": { "CW1": { "dob": true, "country": true

}, "CW2": { "dob": null, "country": null

} }

o Possible values for dob and country are true, false and null (no information). These coincidences are relevant for taking a decision with our business logic.

o country is always null for CW2 (see detailed information below)

! role – person’s role (if found)

! notes – information about the person (if found)

! sanctions – sanctions imposed on the person (if found)

! folder_meta – folder metadata (at the analysis launch)

! fields_4stop – attributes transferred when calling 4stop API method

! response – original analyzer’s response in the following format:

o rules_triggered – rules triggered (as set in 4stop dashboard)

o scrubber_results:

▪ compliance_ watchlist – coincidence found by provider 1

▪ compliance_watchlist2 – coincidence found by provider 2

– 80 –

▪ compliance_watchlist3 – coincidence found by provider 3 (not yet implemented/used!)

In the process of a person analysis coincidences are searched for in external databases. Different providers are used for these searches. Their provisional names are CW1 and CW2. Different providers use different response formats.

This is why rules_triggered is linked to compliance_watchlist and compliance_watchlist2.

! If a coincidence is found in compliance_watchlist, a respective mandatory record in rules_triggered is made.

! But compliance_watchlist and compliance_watchlist2 contain only one object always, whereas the number of coincidences may be more than one.

! Example: Two coincidences for CW1 are reflected in rules_triggered:

o Compliance: CW: Politically Exposed Person - PEP (Extra as Country Matches)

o Compliance: CW: Politically Exposed Person - PEP

! Note that compliance_watchlist contains always only one record 9. Photo expert service

9.1. Input parameters

Following parameters are available:

! get_all_results – boolean flag indicating whether results should be obtained or all images or only for those with potential incidents of photographic compilation intervention

! lang – language locale for results output

! automated_forgery_flags – array of flags for automatic image analysis launch

Example: {

– 81 –

"analyses": [ { "type": "forensic", "params": { "get_all_results": false, "lang": "ru", "automated_forgery_flags": [ "DQT_RED", "CLONES_RED"

] }

} ]

}

9.2. Output parameters

Along with basic attributes of analysis response following additional fields are used:

! confs – dictionary of configurations transferred at the analysis launch (A copy of params field provided at the analyzer launch)

! results_data – contains general information about the processed analysis, and namely:

o type – response status, always success in case of a successful finish

o risk_score – maximal risk level among all images sent to analysis

o result_flag – result flag:

▪ 0 – all images are OK

▪ 1 – incident images were found

o result_color – overall color evaluation defined by the most risky result among all processed images. Possible values:

▪ lime – no risk

▪ yellow – low risk

▪ orange – average risk

– 82 –

▪ red – the highest risk level

o imagesIncident – number of incident images among all uploaded images

o imagesUploaded – number of images uploaded for analysis

o result_message – text commentary concerning the results of image review

! For each source image result_images contains in field results_data a detailed processing report, and namely:

o imgID – image identifier in the photo expertise system

o imgName – original name of the image file from head-end API

o imgResult – short conclusion for the image

o imgStatus – status/color of the image

o imgComment – full conclusion for the image

o risk_score – risk score for the image

o imgExpertAnalyseList – array of applied expert analyses

o imgExpertAnalyseLinks – array of links to results of applied expert analyses

o imgMeta – extracted image metadata (EXIF fields) Example: {

"time_created": 1528980530, "time_updated": 1528980563, "meta_data": null, "analyse_id": "911e777a-ace1-410c-

a424-06f32d4a4b4e", "folder_id": "c0268296-724d-4c6a-

a900-2f90bff032fd", "type": "FORENSIC",

– 83 –

"state": "FINISHED", "results_data": {

"type": "success", "risk_score": "no_risk", "result_flag": 0, "result_color": "lime", "imagesIncident": "0", "imagesUploaded": "1", "result_message": null

}, "error_message": null, "error_code": null, "confs": {


"DQT_RED", "CLONES_RED"

] }, "source_images": [

{ "time_created": 1528980492, "time_updated": 1528980492, "meta_data": {}, "image_id": "9b941079-7726-4139-bed7-

bb5c7291e3b4", "original_url": "http://dev.oz-

services.ru/static/c0268296-724d-4c6a- a900-2f90bff032fd/9b941079-7726-4139-bed7- bb5c7291e3b4.jpeg",

"thumb_url": "http://dev.oz- services.ru/static/c0268296-724d-4c6a- a900-2f90bff032fd/9b941079-7726-4139-bed7- bb5c7291e3b4_thumb.jpeg",

"type": "FOLDER", "original_name": "photo_81693_1.jpg"

} ], "results_images": [

{ "analyse_id": "911e777a-ace1-410c-

a424-06f32d4a4b4e", "source_image_id": "9b941079-7726-4139-

bed7-bb5c7291e3b4", "results_data": {

"imgID": "t78079", "imgMeta": {

"maker": "", "model": "",

– 84 –

http://dev.oz-/

http://dev.oz-/

"",

"",

"",

"",

"",

""

"width": "1920", "height": "1440", "quality": "80", "gps_link": "", "software": "", "width_exif": null, "height_exif": null, "exif_software_modified": "", "datetime_create_exif_text":

"exif_gpsinfo_gpstimestamp":

"exif_image_timezoneoffset":

"exif_image_previewdatetime":

"datetime_digitize_exif_text":

"exif_image_datetimeoriginal":

}, "imgName": "9b941079-7726-4139-

bed7-bb5c7291e3b4.jpeg", "imgResult": "no deviations

found", "imgStatus": "lime", "imgComment": "High level

of trust.The image was compressed too much/too often. The analysis of this image may be inaccurate. Min. threshold: 500 kB for file size and 640x480 pixels for image resolution.",

"risk_score": "no_risk", "imgExpertAnalyseList": [], "imgExpertAnalyseLinks": []

}, "output_images": []

} ], "results_group": []

}

10. Document analysis service 10.1. General operation logic

All images from the uploaded folder undergo an independent expert examination that consists of following steps:

– 85 –

! Attempt to recognize in the image and cut out separate pages of a document

! Attempt to recognize a type of found document (RF Passport, USA Driver License etc.)

! Extraction of key graphical fields from received shots (person’s picture in the document, signature, holograms etc.)

! Search and recognition of relevant areas for document analysis in a shot, including:

o Machine readable areas

o Barcodes

o Text fields

! Attempt to evaluate data validity for all detected areas and recognized data, including:

o Individual

o Identity of fields detected by two or more algorithms (e. g. in a machine readable area and in a text field)

10.2. Structure of analysis results’ description

In addition to standard description of analysis results the feature of document analytics adds following fields:

! document_name – definite type of document

! text_fields – array of entries with description of recognized text fields, each of them being a dictionary:

o field_type – type of field

o field_name – name of field

o mrz – value from machine readable area

o barcode – value from barcode

– 86 –

o visual – value from graphic area

o verification – dictionary with description of results of text fields’ verification

▪ mrz – result of machine readable area verification

▪ barcode – result of barcode verification

▪ visual – result of graphic area verification

▪ mrz-barcode – verification of conformity of values from machine readable area and barcode

▪ mrz-visual – verification of conformity of values from machine readable area and graphic area

▪ visual-barcode – verification of conformity of values from machine readable area and barcode

! document_images – array of entries of Image type with document pages cut out from an image

! graphics_fields – array of key graphic fields extracted from document, each entry being an object of Image type with an additional dictionary meta_info that contains the following keys

o field_type – type of graphic field

o field_name – name of graphic field

! source_media – array of source images from the analyzed folder (this array may have only one entry because all images are analyzed independently within the current logic)

– 87 –

10.3. Basic constants 10.3.1. Possible values for text fields’ verification results

Name Meaning Comment

Verification algorithm Disabled 0 N/A for the field

Verified 1 Verification passed

NotVerified 2 Verification failed

CompareTrue 3 Values agree

CompareFalse 4 Values don’t agree

NB: First three values apply to individual verification of fields (e. g. ‘text field value in machine readable area is valid’)

NB2: Values Disabled, CompareTrue, CompareFalse apply only to comparison of text field values analyzed with the use of different algorithms.

– 88 –

10.3.2. Possible values for graphic fields

Portrait 201

Fingerprint 202

Eye 203

Signature 204

BarCode 205

Proof_Of_Citizenship 206

Document_Front 207

Document_Rear 208

ColorDynamic 209

GhostPortrait 210

Other 250

Finger_LeftThumb 300

Finger_LeftIndex 301

Finger_LeftMiddle 302

Finger_LeftRing 303

Finger_LeftLittle 304

Finger_RightThumb 305

Finger_RightIndex 306

Finger_RightMiddle 307

Finger_RightRing 308

Finger_RightLittle 309

10.3.3. Possible values for text fields

– 89 –

Document_Class_Code 0

Issuing_State_Code 1

Document_Number 2

Date_of_Expiry 3

Date_of_Issue 4

Date_of_Birth 5

Place_of_Birth 6

Personal_Number 7

Surname 8

Given_Names 9

Mothers_Name 10

Nationality 11

Sex 12

Height 13

Weight 14

Eyes_Color 15

Hair_Color 16

Address 17

Donor 18

Social_Security_Number 19

DL_Class 20

DL_Endorsed 21

DL_Restriction_Code 22

DL_Under_21_Date 23

Authority 24

Surname_And_Given_Names 25

Nationality_Code 26

Passport_Number 27

Invitation_Number 28

– 90 –

Visa_ID 29

Visa_Class 30

Visa_SubClass 31

MRZ_String1 32

MRZ_String2 33

MRZ_String3 34

MRZ_Type 35

Optional_Data 36

Document_Class_Name 37

Issuing_State_Name 38

Place_of_Issue 39

Document_Number_Checksum 40

Date_of_Birth_Checksum 41

Date_of_Expiry_Checksum 42

Personal_Number_Checksum 43

FinalChecksum 44

Passport_Number_Checksum 45

Invitation_Number_Checksum 46

Visa_ID_Checksum 47

Surname_And_Given_Names_Checksum 48

Visa_Valid_Until_Checksum 49

Other 50

MRZ_Strings 51

Name_Suffix 52

Name_Prefix 53

Date_of_Issue_Checksum 54

Date_of_Issue_CheckDigit 55

Document_Series 56

RegCert_RegNumber 57

– 91 –

RegCert_CarModel 58

RegCert_CarColor 59

RegCert_BodyNumber 60

RegCert_CarType 61

RegCert_MaxWeight 62

Reg_Cert_Weight 63

Address_Area 64

Address_State 65

Address_Building 66

Address_House 67

Address_Flat 68

Place_of_Registration 69

Date_of_Registration 70

Resident_From 71

Resident_Until 72

Authority_Code 73

Place_of_Birth_Area 74

Place_of_Birth_StateCode 75

Address_Street 76

Address_City 77

Address_Jurisdiction_Code 78

Address_Postal_Code 79

Document_Number_CheckDigit 80

Date_of_Birth_CheckDigit 81

Date_of_Expiry_CheckDigit 82

Personal_Number_CheckDigit 83

FinalCheckDigit 84

Passport_Number_CheckDigit 85

Invitation_Number_CheckDigit 86

– 92 –

Visa_ID_CheckDigit 87

Surname_And_Given_Names_CheckDigit 88

Visa_Valid_Until_CheckDigit 89

Permit_DL_Class 90

Permit_Date_of_Expiry 91

Permit_Identifier 92

Permit_Date_of_Issue 93

Permit_Restriction_Code 94

Permit_Endorsed 95

Issue_Timestamp 96

Number_of_Duplicates 97

Medical_Indicator_Codes 98

Non_Resident_Indicator 99

Visa_Type 100

Visa_Valid_From 101

Visa_Valid_Until 102

Duration_of_Stay 103

Number_of_Entries 104

Day 105

Month 106

Year 107

Unique_Customer_Identifier 108

Commercial_Vehicle_Codes 109

AKA_Date_of_Birth 110

AKA_Social_Security_Number 111

AKA_Surname 112

AKA_Given_Names 113

AKA_Name_Suffix 114

AKA_Name_Prefix 115

– 93 –

Mailing_Address_Street 116

Mailing_Address_City 117

Mailing_Address_Jurisdiction_Code 118

Mailing_Address_Postal_Code 119

Audit_Information 120

Inventory_Number 121

Race_Ethnicity 122

Jurisdiction_Vehicle_Class 123

Jurisdiction_Endorsement_Code 124

Jurisdiction_Restriction_Code 125

Family_Name 126

Given_Names_RUS 127

Visa_ID_RUS 128

Fathers_Name 129

Fathers_Name_RUS 130

Surname_And_Given_Names_RUS 131

Place_Of_Birth_RUS 132

Authority_RUS 133

Issuing_State_Code_Numeric 134

Nationality_Code_Numeric 135

Engine_Power 136

Engine_Volume 137

Chassis_Number 138

Engine_Number 139

Engine_Model 140

Vehicle_Category 141

Identity_Card_Number 142

Control_No 143

Parrent_s_Given_Names 144

– 94 –

Second_Surname 145

Middle_Name 146

RegCert_VIN 147

RegCert_VIN_CheckDigit 148

RegCert_VIN_Checksum 149

Line1_CheckDigit 150



Line1_Checksum 153

Line2_Checksum 154

Line3_Checksum 155

RegCert_RegNumber_CheckDigit 156

RegCert_RegNumber_Checksum 157

RegCert_Vehicle_ITS_Code 158

Card_Access_Number 159

Marital_Status 160

Company_Name 161

Special_Notes 162

Surname_of_Spose 163

Tracking_Number 164

Booklet_Number 165

Children 166

Copy 167

Serial_Number 168

Dossier_Number 169

AKA_Surname_And_Given_Names 170

Territorial_Validity 171

MRZ_Strings_With_Correct_CheckSums 172

DL_CDL_Restriction_Code 173

– 95 –

DL_Under_18_Date 174

DL_Record_Created 175

DL_Duplicate_Date 176

DL_Iss_Type 177

Military_Book_Number 178

Destination 179

Blood_Group 180

Sequence_Number 181

RegCert_BodyType 182

RegCert_CarMark 183

Transaction_Number 184

Age 185

Folio_Number 186

Voter_Key 187

Address_Municipality 188

Address_Location 189

Section 190

OCR_Number 191

Federal_Elections 192

Reference_Number 193

Optional_Data_Checksum 194

Optional_Data_CheckDigit 195

Visa_Number 196

Visa_Number_Checksum 197

Visa_Number_CheckDigit 198

Voter 199

Previous_Type 200

FieldFromMRZ 220

CurrentDate 221

– 96 –

Status_Date_of_Expiry 251

Banknote_Number 252

CSC_Code 253

Artistic_Name 254

Academic_Title 255

Address_Country 256

Address_Zipcode 257

eID_Residence_Permit1 258

eID_Residence_Permit2 259

eID_PlaceOfBirth_Street 260

eID_PlaceOfBirth_City 261

eID_PlaceOfBirth_State 262

eID_PlaceOfBirth_Country 263

eID_PlaceOfBirth_Zipcode 264

CDL_Class 265

DL_Under_19_Date 266

Weight_pounds 267

Limited_Duration_Document_Indicator 268

Endorsement_Expiration_Date 269

Revision_Date 270

Compliance_Type 271

Family_name_truncation 272

First_name_truncation 273

Middle_name_truncation 274

Exam_Date 275

Organization 276

Department 277

Pay_Grade 278

Rank 279

– 97 –

Benefits_Number 280

Sponsor_Service 281

Sponsor_Status 282

Sponsor 283

Relationship 284

USCIS 285

Category 286

Conditions 287

Identifier 288

Configuration 289

Discretionary_data 290

Line1_Optional_Data 291



EQV_Code 294

ALT_Code 295

Binary_Code 296

Pseudo_Code 297

Fee 298

Stamp_Number 299

GNIB_Number 340

Dept_Number 341

Telex_Code 342

Allergies 343

Sp_Code 344

Court_Code 345

Cty 346

Sponsor_SSN 347

DoD_Number 348

– 98 –

MC_Novice_Date 349

DUF_Number 350

AGY 351

PNR_Code 352

From_Airport_Code 353

To_Airport_Code 354

Flight_Number 355

Date_of_Flight 356

Seat_Number 357

Date_of_Issue_Boarding_Pass 358

CCW_Until 359

Reference_Number_Checksum 360

Reference_Number_CheckDigit 361

Room_Number 362

Religion 363

RemainderTerm 364

Electronic_Ticket_Indicator 365

Compartment_Code 366

CheckIn_Sequence_Number 367

Airline_Designator_of_boarding_pass_issuer 368

Airline_Numeric_Code 369

Ticket_Number 370

Frequent_Flyer_Airline_Designator 371

Frequent_Flyer_Number 372

Free_Baggage_Allowance 373

PDF417Codec 374

Identity_Card_Number_Checksum 375

Identity_Card_Number_CheckDigit 376

Veteran 377

– 99 –

DLClassCode_A1_From 378

DLClassCode_A1_To 379

DLClassCode_A1_Notes 380

DLClassCode_A_From 381

DLClassCode_A_To 382

DLClassCode_A_Notes 383

DLClassCode_B_From 384

DLClassCode_B_To 385

DLClassCode_B_Notes 386

DLClassCode_C1_From 387

DLClassCode_C1_To 388

DLClassCode_C1_Notes 389

DLClassCode_C_From 390

DLClassCode_C_To 391

DLClassCode_C_Notes 392

DLClassCode_D1_From 393

DLClassCode_D1_To 394

DLClassCode_D1_Notes 395

DLClassCode_D_From 396

DLClassCode_D_To 397

DLClassCode_D_Notes 398

DLClassCode_BE_From 399

DLClassCode_BE_To 400

DLClassCode_BE_Notes 401

DLClassCode_C1E_From 402

DLClassCode_C1E_To 403

DLClassCode_C1E_Notes 404

DLClassCode_CE_From 405

DLClassCode_CE_To 406

– 100

DLClassCode_CE_Notes 407

DLClassCode_D1E_From 408

DLClassCode_D1E_To 409

DLClassCode_D1E_Notes 410

DLClassCode_DE_From 411

DLClassCode_DE_To 412

DLClassCode_DE_Notes 413

DLClassCode_M_From 414

DLClassCode_M_To 415

DLClassCode_M_Notes 416

DLClassCode_L_From 417

DLClassCode_L_To 418

DLClassCode_L_Notes 419

DLClassCode_T_From 420

DLClassCode_T_To 421

DLClassCode_T_Notes 422

DLClassCode_AM_From 423

DLClassCode_AM_To 424

DLClassCode_AM_Notes 425

DLClassCode_A2_From 426

DLClassCode_A2_To 427

DLClassCode_A2_Notes 428

DLClassCode_B1_From 429

DLClassCode_B1_To 430

DLClassCode_B1_Notes 431

Surname_at_Birth 432

Civil_Status 433

Number_of_Seats 434

Number_of_Standing_Places 435

– 101

Max_Speed 436

Fuel_Type 437

EC_Environmental_Type 438

Power_Weight_Ratio 439

Max_Mass_of_Trailer_Braked 440

Max_Mass_of_Trailer_Unbraked 441

Transmission_Type 442

Trailer_Hitch 443

Accompanied_by 444

Police_District 445

First_Issue_Date 446

Payload_Capacity 447

Number_of_Axels 448

Permissible_Axle_Load 449

Precinct 450

Invited_by 451

Purpose_of_Entry 452

Skin_Color 453

Complexion 454

Airport_From 455

Airport_To 456

Airline_Name 457

Airline_Name_Frequent_Flyer 458

In_Tanks 460

Exept_In_Tanks 461

Fast_Track 462

Owner 463

MRZ_Strings_ICAO_RFID 464

Number_of_Card_Issuance 465

– 102

Number_of_Card_Issuance_Checksum 466

Number_of_Card_Issuance_CheckDigit 467

Century_Date_of_Birth 468 11. Biometrics service

11.1. Operation logic

Biometrics analyzer operates as follows:

! Search for one face in the shots for all images in a folder. If an image does not contain any faces, it is not included into the common vector of analyzed faces

! If less than 2 face images remain for final processes, the analyzer aborts with error 202: ‘Biometry analyse requires at least 2 images to process’.

! A pair-wise comparison is performed for all detected faces (reliability index) that outputs a numeric value in the range 0 to 1.

! The most different face images (according to reliability metrics) and the final decision are communicated as the results of processing with the analyzer.

11.2. Structure of analyzer results’ description

The results of processing with the analyzer are represented in the analysis response as follows:

! faces – contains an array of face images identified in the folder

! Following information is saved in the field results:

o min_cofidence – minimal value of reliability index for all pairs of faces

o max_cofidence – maximal value of reliability index for all pairs of faces

– 103

o decision – final decision on matching/mismatching of faces (true/false)

o minfaces – array containing a pair of face image identifiers (from the field faces) with the minimal reliability index

– 104

Documents

GATEWAY API SERVER FOR ACCESSING OZ FORENSICS SERVICES · Editing a company profile 24 6.2.10. Deleting a company 24 6.3. Folders 25 6.3.1. Model 25 6.3.2. ... 3XX have ancillary