openapi: 3.0.3
info:
  title: Acuant FRM Face Recognition API
  description: >-
    Face recognition and matching API that compares two facial images and
    returns a match score. Used alongside document verification to confirm
    the person presenting an ID matches a live selfie capture. Supports
    regional endpoints for USA, EU, and AUS deployments.
  version: '1.0'
  contact:
    name: Acuant Support
    url: https://support.acuant.com
  x-api-id: acuant:frm
servers:
  - url: https://frm.acuant.net
    description: USA Production
  - url: https://eu.frm.acuant.net
    description: EU Production
  - url: https://aus.frm.acuant.net
    description: AUS Production
  - url: https://preview.face.acuant.net
    description: Preview / Sandbox
security:
  - BearerAuth: []
  - BasicAuth: []
tags:
  - name: Face Match
    description: Facial comparison and matching operations
paths:
  /api/v1/facematch:
    post:
      operationId: compareFaces
      summary: Compare two facial images
      description: >-
        Compares two facial images and returns a match score indicating the
        likelihood that both images depict the same person. Typically used
        to match a selfie against a photo extracted from an identity document.
      tags:
        - Face Match
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FaceMatchRequest'
            example:
              Settings:
                SubscriptionId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
              Data:
                ImageOne: "<base64-encoded-face-image-1>"
                ImageTwo: "<base64-encoded-face-image-2>"
      responses:
        '200':
          description: Face match result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceMatchResult'
              example:
                Score: 85.5
                IsMatch: true
                TransactionId: "txn-a1b2c3d4"
        '400':
          description: Invalid request or image quality insufficient
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Inactive subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer token obtained from the ACAS (Cloud Authentication Service).
        Include SubscriptionId in request body alongside the bearer token.
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication with Acuant credentials.

  schemas:
    Error:
      type: object
      properties:
        Code:
          type: integer
          description: Error code
        Message:
          type: string
          description: Error description

    FaceMatchSettings:
      type: object
      required:
        - SubscriptionId
      properties:
        SubscriptionId:
          type: string
          format: uuid
          description: Acuant subscription identifier

    FaceMatchData:
      type: object
      required:
        - ImageOne
        - ImageTwo
      properties:
        ImageOne:
          type: string
          format: byte
          description: Base64-encoded first facial image (e.g., from identity document)
        ImageTwo:
          type: string
          format: byte
          description: Base64-encoded second facial image (e.g., live selfie)

    FaceMatchRequest:
      type: object
      required:
        - Settings
        - Data
      properties:
        Settings:
          $ref: '#/components/schemas/FaceMatchSettings'
        Data:
          $ref: '#/components/schemas/FaceMatchData'

    FaceMatchResult:
      type: object
      properties:
        Score:
          type: number
          format: float
          minimum: 0
          maximum: 100
          description: >-
            Match confidence score from 0 to 100. Higher values indicate
            greater likelihood the images depict the same person.
        IsMatch:
          type: boolean
          description: Whether the match score exceeds the configured threshold
        TransactionId:
          type: string
          description: Unique identifier for this face match transaction
        Error:
          type: string
          nullable: true
          description: Error message if face detection or matching failed
        ErrorCode:
          type: integer
          nullable: true
          description: Numeric error code if an error occurred