common.yml

openapi: 3.0.3

components:
  parameters:
    page:
      name: page
      in: query
      description: "The page number to get a list of persons or groups."
      schema:
        type: integer
        default: 1
    size:
      name: size
      in: query
      description: "The page size with a list of persons or groups, items."
      schema:
        type: integer
        default: 1000
    x-request:
      in: header
      name: X-RequestID
      description: "Request header label."
      schema:
        type: string
    transactionId:
      in: query
      name: transactionId
      required: true
      description: "ID of the current liveness transaction."
      schema:
        type: string
        format: uuid

  responses:
    BadLicense:
      description: "Bad license. Either the server or request does not contain a valid license."
    BadRequest:
      description: "Bad request. Check your input data."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OperationLog"

  schemas:
    ProcessParam:
      type: object
      description: "The processing parameters."
      properties:
        scenario:
          $ref: "#/components/schemas/FaceQualityScenarios"
        onlyCentralFace:
          type: boolean
          description: "Whether to process only the central face in the image. If set to `false`, all the faces are processed."
          example: false
        outputImageParams:
          $ref: "#/components/schemas/OutputImageParams"
        quality:
          $ref: "#/components/schemas/QualityRequest"
        attributes:
          description: "If set, the selected attributes, such as age or emotions, are evaluated."
          type: object
          properties:
            config:
              $ref: "./common.yml#/components/schemas/AttributeConfigList"

    OutputImageParams:
      type: object
      description: "Allows to process the uploaded image according to the indicated settings."
      properties:
        backgroundColor:
          description: "The RGB value for the background color: the silhouette of a person is cut out and the background is filled with this color."
          $ref: "#/components/schemas/RGB"
        crop:
          $ref: "#/components/schemas/Crop"

    QualityRequest:
      type: object
      description: "If set, the face image quality check is performed according to the set scenario or characteristics."
      properties:
        backgroundMatchColor:
          description: "The RGB value for the background color: the silhouette of a person is cut out and the background is filled with this color."
          $ref: "#/components/schemas/RGB"
        config:
          $ref: "#/components/schemas/QualityConfigList"

    Crop:
      type: object
      description: "Whether to return a Base64-encoded image of an aligned and cropped portrait in the `crop` field. Alignment is performed according to `type`; if a head on the original image is tilted, for the returned portrait it is aligned in a straight vertical line. If there are more than one face in the photo, all the faces are detected and processed, and separate portraits for each face are returned. So, if there are five people in the photo, you'll get five processed portraits. Each portrait can be downloaded."
      properties:
        type:
          $ref: "#/components/schemas/FaceImageQualityAlignType"
          description: "The aspect ratio according to which face alignment is performed, see the [FaceImageQualityAlignType enum](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-image-quality-align-type/). <br><br>To get a thumbnail with dimensions 3x4, set `0`."
          example: 1
        padColor:
          $ref: "#/components/schemas/RGB"
          description: "The RGB value of a color for filling background behind a person's silhouette and for aligning the image."
        size:
          type: array
          items:
            type: integer
          minItems: 2
          maxItems: 2
          description: "The resize value in case `type` matches this value. If it doesn't, no resize is performed."
          example: [300, 400]
        returnOriginalRect:
          type: boolean
          description: "Whether to return the coordinates of the rectangle with the face in the original image prepared for the face crop."
          example: true

    QualityConfigList:
      type: array
      description: "The list of quality check characteristics."
      items:
        $ref: "#/components/schemas/QualityConfig"

    QualityConfig:
      type: object
      description: "The configuration that defines the list of returned quality check characteristics."
      properties:
        name:
          description: "The name of the characteristic."
          $ref: "#/components/schemas/FaceQualityConfigName"
          example: "Emotion"
        range:
          type: array
          items:
            type: number
            format: float
          minItems: 2
          maxItems: 2
          description: "The range of applicable values for this characteristic. If the returned in the response value fits this range, the characteristic is identified as compliant with the requirements."
          example: [x, y]

    AttributeConfigList:
      type: array
      description: "The list of attributes for evaluation."
      items:
        $ref: "#/components/schemas/AttributeConfig"

    AttributeConfig:
      type: object
      description: "The configuration that defines the list of returned attribute check characteristics."
      properties:
        name:
          description: "The name of the characteristic."
          $ref: "#/components/schemas/FaceAttribute"
          example: "Emotion"

    QualityDetailsGroups:
      type: object
      properties:
        groupId:
          description: "The ID of the characteristics group."
          $ref: "#/components/schemas/FaceImageQualityGroups"
        name:
          $ref: "#/components/schemas/FaceImageQualityGroupsStrings"
          description: "The name of the characteristics group."
        totalCount:
          type: integer
          description: "The total number of characteristics in the group."
          example: 5
        compliantCount:
          type: integer
          description: "The number of compliant characteristics in the group."
          example: 4

    QualityDetail:
      type: object
      properties:
        groupId:
          description: "The ID of the characteristics group."
          $ref: "#/components/schemas/FaceImageQualityGroups"
          example: 0
        name:
          $ref: "#/components/schemas/FaceQualityConfigName"
          description: "The name of the characteristic."
          example: "Roll"
        range:
          type: array
          description: "The range of set values for this characteristic."
          items:
            type: number
            format: float
          minItems: 2
          maxItems: 2
          example: [x, y]
        status:
          $ref: "#/components/schemas/FaceImageQualityStatus"
          example: 1
          description: "The assessment status."
        value:
          type: number
          format: float
          description: "The assessed value for the characteristic, returned in the set units."
          example: 0.0

    RGB:
      type: array
      description: "The RGB value of a color for filling background behind a person's silhouette and for aligning the image." 
      items:
        type: integer
      minItems: 3
      maxItems: 3
      example: [128, 128, 128]

    FaceImageQualityStatus:
      type: integer
      description: "The processing status returned for each assessed quality characteristic." 
      enum:
        - 0
        - 1
        - 2
      x-enum-varnames:
        - QUALITY_STATUS_FALSE
        - QUALITY_STATUS_TRUE
        - QUALITY_STATUS_UNDETERMINED

    FaceQualityScenarios:
      type: string
      description: "Face detection scenario. If applied and the scenario is found, the parameters are set automatically and any other parameters mentioned in the request are ignored.
      

      If not set, left empty, or the name is not found, the processing is performed according to the set parameters.


      You can find detailed descriptions of available scenarios on the [Scenarios page](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/usage/face-detection/scenarios/)."
      enum:
        - "OldMode"
        - "QualityFull"
        - "QualityICAO"
        - "QualityVisaSchengen"
        - "QualityVisaUSA"
        - "CropCentralFace"
        - "CropAllFaces"
        - "Thumbnail"
        - ""
      x-enum-varnames:
        - OLD_MODE
        - QUALITY_FULL
        - QUALITY_ICAO
        - QUALITY_VISA_SCHENGEN
        - QUALITY_VISA_USA
        - CROP_CENTRAL_FACE
        - CROP_ALL_FACES
        - THUMBNAIL
        - EMPTY

    FaceImageQualityGroups:
      type: integer
      description: "Face image quality group types for face image quality assessment."
      enum:
        - 1
        - 2
        - 3
        - 4
        - 5
        - 6
        - 7
        - 8
      x-enum-varnames:
        - IMAGE_CHARACTERISTICS
        - HEAD_SIZE_AND_POSITIONS
        - FACE_QUALITY
        - EYES_CHARACTERISTICS
        - SHADOWS_AND_LIGHTNING
        - POSE_AND_EXPRESSION
        - HEAD_OCCLUSION
        - BACKGROUND
    FaceImageQualityGroupsStrings:
      type: string
      description: "Face image quality group types for face image quality assessment."
      enum:
        - "ImageCharacteristics"
        - "HeadSizeAndPosition"
        - "FaceQuality"
        - "EyesCharacteristics"
        - "ShadowsAndLightning"
        - "PoseAndExpression"
        - "HeadOcclusion"
        - "Background"
      x-enum-varnames:
        - IMAGE_CHARACTERISTICS
        - HEAD_SIZE_AND_POSITIONS
        - FACE_QUALITY
        - EYES_CHARACTERISTICS
        - SHADOWS_AND_LIGHTNING
        - POSE_AND_EXPRESSION
        - HEAD_OCCLUSION
        - BACKGROUND

    FaceQualityConfigName:
      type: string
      description: "The name of the quality check characteristic. For definitions, see the [FaceQualityConfigName enum](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-quality-config-name/)."
      enum:
        - "ImageWidth"
        - "ImageHeight"
        - "ImageWidthToHeight"
        - "ImageChannelsNumber"
        - "PaddingRatio"
        - "FaceMidPointHorizontalPosition"
        - "FaceMidPointVerticalPosition"
        - "HeadWidthRatio"
        - "HeadHeightRatio"
        - "EyesDistance"
        - "Yaw"
        - "Pitch"
        - "Roll"
        - "BlurLevel"
        - "NoiseLevel"
        - "EyeRightClosed"
        - "EyeLeftClosed"
        - "EyeRightOccluded"
        - "EyeLeftOccluded"
        - "EyesRed"
        - "EyeRightCoveredWithHair"
        - "EyeLeftCoveredWithHair"
        - "OffGaze"
        - "FaceDynamicRange"
        - "UnnaturalSkinTone"
        - "TooDark"
        - "TooLight"
        - "FaceGlare"
        - "ShadowsOnFace"
        - "DarkGlasses"
        - "ReflectionOnGlasses"
        - "FramesTooHeavy"
        - "FaceOccluded"
        - "HeadCovering"
        - "BackgroundUniformity"
        - "ShadowsOnBackground"
        - "OtherFaces"
        - "ShouldersPose"
        - "ExpressionLevel"
        - "MouthOpen"
        - "ForeheadCovering"
        - "Smile"
        - "StrongMakeup"
        - "Headphones"
        - "MedicalMask"
        - "BackgroundColorMatch"
        - "ArtFace"
        - "ContactLenses"
      x-enum-varnames:
        - IMAGE_WIDTH
        - IMAGE_HEIGHT
        - IMAGE_WIDTH_TO_HEIGHT
        - IMAGE_CHANNELS_NUMBER
        - PADDING_RATIO
        - FACE_MID_POINT_HORIZONTAL_POSITION
        - FACE_MID_POINT_VERTICAL_POSITION
        - HEAD_WIDTH_RATIO
        - HEAD_HEIGHT_RATIO
        - EYES_DISTANCE
        - YAW
        - PITCH
        - ROLL
        - BLUR_LEVEL
        - NOISE_LEVEL
        - EYE_RIGHT_CLOSED
        - EYE_LEFT_CLOSED
        - EYE_RIGHT_OCCLUDED
        - EYE_LEFT_OCCLUDED
        - EYES_RED
        - EYE_RIGHT_COVERED_WITH_HAIR
        - EYE_LEFT_COVERED_WITH_HAIR
        - OFF_GAZE
        - FACE_DYNAMIC_RANGE
        - UNNATURAL_SKIN_TONE
        - TOO_DARK
        - TOO_LIGHT
        - FACE_GLARE
        - SHADOWS_ON_FACE
        - DARK_GLASSES
        - REFLECTION_ON_GLASSES
        - FRAMES_TOO_HEAVY
        - FACE_OCCLUDED
        - HEAD_COVERING
        - BACKGROUND_UNIFORMITY
        - SHADOWS_ON_BACKGROUND
        - OTHER_FACES
        - SHOULDERS_POSE
        - EXPRESSION_LEVEL
        - MOUTH_OPEN
        - FOREHEAD_COVERING
        - SMILE
        - STRONG_MAKEUP
        - HEADPHONES
        - MEDICAL_MASK
        - BACKGROUND_COLOR_MATCH
        - ART_FACE
        - CONTACT_LENSES

    FaceSDKResult:
      type: object
      required:
        - code
      properties:
        code:
          $ref: "#/components/schemas/FaceSDKResultCode"

    ImageData:
      description: "Base64-encoded image."
      type: string
      format: byte

    OperationLog:
      type: object
      properties:
        statusCode:
          type: integer
          description: "Status code."
        type:
          type: string
          description: "Error type."
        msg:
          type: string
          description: "Error message."
        metadata:
          type: object
          additionalProperties: true
          description: "A free-form object containing group's extended attributes."
    Page:
      type: object
      description: "Information about current page number and total pages count"
      properties:
        page:
          type: integer
          description: "Current page number."
          example: 1
        totalPages:
          type: integer
          description: "Total number of pages."
          example: 2

    Bytes:
      type: string
      format: binary

    FaceImageQualityAlignType:
      type: integer
      description: "The aspect ratio according to which face alignment is performed. See the [FaceImageQualityAlignType enum](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-image-quality-align-type/). To get a thumbnail with aspect ratio 3:4, set `0`."
      enum:
        - 0
        - 1
        - 2
        - 3
        - 4
      x-enum-varnames:
        - ALIGN_3x4
        - ALIGN_4x5
        - ALIGN_2x3
        - ALIGN_1x1
        - ALIGN_7x9

    FaceSDKResultCode:
      type: integer
      description: "The result code, see the [FaceSDKResultCode enum](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-sdk-result-code/)."
      enum:
        - 0
        - 1
        - 2
        - 3
        - 4
        - 5
        - 6
        - 7
        - 199
        - 200
        - 201
        - 202
        - 203
        - 224
        - 227
        - 228
        - 229
        - 230
        - 231
        - 232
        - 233
        - 234
        - 235
        - 236
        - 237
        - 238
        - 239
        - 240
        - 242
        - 243
        - 244
        - 245
        - 246
        - 247
        - 248
        - 249
        - 250
        - 251
        - 252
        - 253
        - 254
      x-enum-varnames:
        - FACER_OK
        - FR_IMAGE_EMPTY
        - FR_FACE_NOT_DETECTED
        - FR_LANDMARKS_NOT_DETECTED
        - FR_FACE_ALIGHNER_FAILED
        - FR_DESCRIPTOR_EXTRACTOR_ERROR
        - FR_IMAGE_DECODE_ERROR
        - FR_INTERNAL_ERROR
        - FACER_CONFIG_ERROR
        - FACER_NO_LICENSE
        - FACER_IS_NOT_INITIALIZED
        - FACER_COMMAND_IS_NOT_SUPPORTED
        - FACER_COMMAND_PARAMS_READ_ERROR
        - FACER_LESS_THAN_TWO_IMAGES_IN_REQUEST
        - FACER_VIDEO_DECODE_ERROR
        - FACER_NOT_ENOUGH_FRAMES
        - FACER_OUTPUT_IS_NOT_DEFINED
        - FACER_CLOSED_EYES_DETECTED
        - FACER_LOW_QUALITY
        - FACER_HIGH_ASYMMETRY
        - FACER_FACE_OVER_EMOTIONAL
        - FACER_SUNGLASSES_DETECTED
        - FACER_SMALL_AGE
        - FACER_HEADDRESS_DETECTED
        - FACER_FACES_NOT_MATCHED
        - FACER_IMAGES_COUNT_LIMIT_EXCEEDED
        - FACER_MEDICINE_MASK_DETECTED
        - FACER_OCCLUSION_DETECTED
        - FACER_FOREHEAD_GLASSES_DETECTED
        - FACER_MOUTH_OPENED
        - FACER_ART_MASK_DETECTED
        - FACER_ELECTRONIC_DEVICE_DETECTED
        - FACER_TRACK_BREAK
        - FACER_WRONG_GEO
        - FACER_WRONG_OF
        - FACER_WRONG_VIEW
        - FACER_TIMEOUT_LIVENESS_TRANSACTION
        - FACER_FAILED_LIVENESS_TRANSACTION
        - FACER_ABORTED_LIVENESS_TRANSACTION
        - FACER_GENERAL_ERROR
        - FACER_PASSIVE_LIVENESS_FAIL

    Thumbnail:
      description: "See `crop` instead."
      deprecated: true
      type: string
      format: byte

    FaceRectangular:
      description: "The rectangular area of a detected face that is represented by a set of four elements: the X and Y coordinates of the top-left point, and the width and height dimensions of the rectangle."
      type: array
      items:
        type: number
      example: [x, y, width, height]

    FaceAttribute:
      type: string
      description: "The name of the attribute. For definitions, see the [FaceAttribute enum](https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-attribute/)."
      enum:
        - "Age"
        - "Emotion"
        - "EyeLeft"
        - "EyeRight"
        - "Smile"
        - "Glasses"
        - "HeadCovering"
        - "ForeheadCovering"
        - "Mouth"
        - "MedicalMask"
        - "Occlusion"
        - "StrongMakeup"
        - "Headphones"
      x-enum-varnames:
        - AGE
        - EMOTION
        - EYE_LEFT
        - EYE_RIGHT
        - SMILE
        - GLASSES
        - HEAD_COVERING
        - FOREHEAD_COVERING
        - MOUTH
        - MEDICAL_MASK
        - OCCLUSION
        - STRONG_MAKEUP
        - HEADPHONES

    ImageSource:
      type: integer
      description: "Face photo image source types: https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/image-source/"
      enum:
        - 1
        - 2
        - 3
        - 4
        - 5
        - 6
      x-enum-varnames:
        - DOCUMENT_PRINTED
        - DOCUMENT_RFID
        - LIVE
        - DOCUMENT_WITH_LIVE
        - EXTERNAL
        - GHOST

    FaceLivenessStatus:
      type: integer
      description: "The liveness assessment status: https://docs.regulaforensics.com/develop/face-sdk/web-service/development/enums/face-liveness-status/"
      enum:
        - 0
        - 1
        - 2
      x-enum-varnames:
        - LVC_REAL
        - LVC_FAKE
        - LVC_UNKNOWN