Merge pull request #96 from regulaforensics/15040-release-6-1

[Release 6.1]

Author: KirylKovaliov

identification.yml

@@ -61,6 +61,9 @@ components:
         name:
           type: string
           description: "Person's name."
+        externalId:
+          type: string
+          description: "Person's ID, used for linking search results to an ID in an external system. Can be set when creating a Person, stored in the database, and included in the search to return only Persons with the specified ID. Optional."
         metadata:
           type: object
           additionalProperties: true
@@ -75,6 +78,9 @@ components:
       type: object
       description: "Person Request body: name and metadata."
       properties:
+        externalId:
+          type: string
+          description: "Person's ID, used for linking search results to an ID in an external system. Can be set when creating a Person, stored in the database, and included in the search to return only Persons with the specified ID. Optional."
         name:
           type: string
           description: "Person's name."

index.yml

@@ -1,6 +1,6 @@
 openapi: 3.0.3
 info:
-  version: 6.1.0
+  version: 6.2.0
   title: Regula Face SDK Web API
   x-logo:
     url: 'https://static-content.regulaforensics.com/Icons/Logos/Regula-logo.svg'

liveness.yml

@@ -7,7 +7,22 @@ paths:
     get:
       tags:
         - liveness 2.0
-      summary: Liveness assessment
+      summary: 'liveness check'
+      description: "To verify the presence of a real person in front of a camera, use the GET `/api/v2/liveness` endpoint. When starting, you can specify `tag` which all attempts to read liveness will be bound to. If left unspecified, the application automatically generates one. The calling application returns `tag` and `transactionId`. One session may include many transactions, and from a transaction ID it is clear which session it belongs to.
+
+
+      When specifying `tag`, note that only Latin uppercase and lowercase letters, digits, and symbols `-` and `_` are allowed. The maximum supported number of characters is 127.
+      
+
+      The metadata (device model, screen data, frame size, app ID and version, OS version, platform, SDK version, etc.), a person's selfie and video of the liveness detection session are stored on the backend at:
+      `faceapi-session/year={year}/month={month}/day={day}/hour={hour}/minute={minute}/{tag}/transactionId`
+      
+
+      By default, liveness checks operate with eventual consistency. This means that when you submit a request and receive a response, the associated data (like the selfie and session video) may be saved after the response is sent. If this doesn't meet your requirements, you can switch to strong consistency; refer to the [Architecture page](https://docs.regulaforensics.com/develop/face-sdk/overview/architecture/#consistency-models) for details.
+
+      
+      To access the liveness transaction data, use GET `/api/v2/liveness?transactionId={transactionId}`.
+      "
       operationId: get_liveness_transaction_info
       responses:
         200:
@@ -24,11 +39,11 @@ components:
       properties:
         code:
           type: integer
-          description: "Result code, one of the FaceSDKResultCode enum values. See the enum: https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-sdk-result-code/"
+          description: "Result code, see the [FaceSDKResultCode enum](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-sdk-result-code/)."
         status:
           type: integer
           default: null
-          description: "Whether the liveness detection is confirmed (0) or not (1)."
+          description: "Whether the liveness detection is confirmed `0` or not `1`."
         tag:
           type: string
           description: "Session identificator, should be unique for each session."
@@ -51,3 +66,16 @@ components:
           type: object
           additionalProperties: true          
           description: "A free-form object containing person's extended attributes."
+        type:
+          $ref: "#/components/schemas/LivenessType"
+
+    LivenessType:
+      type: integer
+      description: "Liveness detection can be performed in two modes: active `0` and passive `1`. [Learn more](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/liveness/#active-and-passive-modes)"
+      default: 0
+      enum:
+        - 0
+        - 1
+      x-enum-varnames:
+        - ACTIVE
+        - PASSIVE

search.yml

@@ -59,6 +59,36 @@ definitions:
         items:
           type: string
           format: uuid
+      filter:
+        $ref: '#/definitions/FilterSearchRequest'
+
+  FilterSearchRequest:
+    type: object
+    description: "Allows to filter the search results based on the Person's `name`. If enabled, only the search results that meet the filter condition will be returned." 
+    properties:
+      op:
+        $ref: '#/definitions/FilterOp'
+      field:
+        type: string
+        description: "`name` of the Person."
+      value:
+        type: array
+        description: "The list of `name` values against which the `field` is compared."
+        items:
+          type: string
+
+  FilterOp:
+    type: string
+    description: "The filter condition, determines the type of comparison to be performed on the `name` values of the Person entity. <br><br>When set to `in`, 
+    the `name` values of the Person should match any of the values specified in the `value` list. <br><br>When set to `nin`, 
+    the `name` values of the Person should not match any of the values specified in the `value` list."
+    enum:
+      - "in"
+      - "nin"
+    x-enum-varnames:
+      - IN
+      - NOT_IN
+
   RecognizeImage:
     allOf:
       - $ref: "./identification.yml#/components/schemas/Image"