> ## Documentation Index
> Fetch the complete documentation index at: https://docs.idmetagroup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Biometrics Face Compare

> Compare two face images and return a similarity score through the passthrough endpoint. This endpoint is commonly used to compare the potrait image from a personal identification document against a face image

## Related endpoint

Face compare answers whether two faces belong to the same person. [Biometrics Verification](/stateless-verification-api/compliance/biometrics-verification) answers whether a single selfie shows a live person. A full remote-identity check usually calls both.


## OpenAPI

````yaml stateless-verification-api/compliance/biometrics-face-compare.openapi.json POST /api/v3/verifications/biometrics-face-compare-passthrough
openapi: 3.0.3
info:
  title: Biometrics Face Compare Passthrough API
  version: 1.0.0
servers:
  - url: https://{environment-subdomain}.idmetagroup.com
    description: Your environment (replace `{environment-subdomain}`)
    variables:
      environment-subdomain:
        default: integrate
        description: IDmeta environment subdomain
security:
  - bearerAuth: []
paths:
  /api/v3/verifications/biometrics-face-compare-passthrough:
    post:
      tags:
        - Compliance Verification
      summary: Biometrics Face Compare
      description: >-
        Compare two face images and return a similarity score.


        **Neither image is ever stored.** Both are decoded, compressed, and
        discarded once the comparison completes. That is the reason to choose
        the passthrough endpoint over flows that persist enrollment data.


        **Image URLs are not accepted.** `image1` and `image2` must be a Base64
        data URI or a multipart file upload. A URL is rejected with `"image1
        must be an uploaded file or base64 image; URLs are not supported."` (or
        the equivalent for `image2`).


        `similarityScore`, `minSimilarityScore` and `verifiedSimilarityScore`
        are all **percentages from 0 to 100** on the same scale.
        `minSimilarityScore` defaults to `50`; `verifiedSimilarityScore`
        defaults to `70`.


        The score decides the outcome: below `minSimilarityScore` → `REJECTED`;
        at or above `verifiedSimilarityScore` → `VERIFIED`; between the two →
        `REVIEW_NEEDED`. All three are completed verifications returned as HTTP
        200, and all three are billed.


        **Both bounds can only be tightened, never loosened.** A
        `minSimilarityScore` below `50` or a `verifiedSimilarityScore` below
        `70` is accepted but has no effect — the default applies. Raising either
        bound makes a match harder to obtain; lowering it cannot make a rejected
        comparison pass. The request succeeds without an error either way. The
        bounds that were applied are **not** returned in the response.


        `verificationStatusCode`: `3` = Verified, `2` = Review Needed, `1` =
        Rejected, `6` = Failed.


        HTTP `400`, `500`, and `502` release the reserved credit. Only a
        completed comparison — verified, review needed, or rejected — is billed.
      operationId: biometricsFaceComparePassthrough
      parameters:
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
            example: Bearer {your_api_token}
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
        - name: Content-Type
          in: header
          required: false
          schema:
            type: string
            default: application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BiometricsFaceCompareRequest'
            examples:
              defaultBands:
                summary: Compare two faces using the default thresholds
                value:
                  image1: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...
                  image2: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...
                  minSimilarityScore: 50
                  verifiedSimilarityScore: 70
                  metadata:
                    customerReference: CUST-10294
              strictBands:
                summary: Compare two faces at stricter thresholds
                value:
                  image1: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...
                  image2: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...
                  minSimilarityScore: 50
                  verifiedSimilarityScore: 95
                  metadata:
                    customerReference: CUST-10294
          multipart/form-data:
            schema:
              type: object
              required:
                - image1
                - image2
              properties:
                image1:
                  type: string
                  format: binary
                  description: First face image file.
                image2:
                  type: string
                  format: binary
                  description: Second face image file.
                minSimilarityScore:
                  type: number
                  minimum: 0
                  maximum: 100
                  default: 50
                verifiedSimilarityScore:
                  type: number
                  minimum: 0
                  maximum: 100
                  default: 70
                metadata:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: >-
            Comparison completed. Verified, review-needed, and rejected outcomes
            all use HTTP 200.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BiometricsFaceCompareSuccessResponse'
              examples:
                verified:
                  summary: Faces match
                  value:
                    success: true
                    message: Biometrics Face Compare processed successfully
                    data:
                      similarityScore: 94.21
                    verificationStatus: VERIFIED
                    verificationStatusCode: 3
                    transactionId: 7b3e9c14-2a68-4d05-91f7-6c8d0b2e4a31
                    verificationType: biometrics_face_compare
                    metadata:
                      customerReference: CUST-10294
                    createdAt: 2026-09-14 04:12:37+0000
                reviewNeeded:
                  summary: Score fell between the thresholds
                  description: '`62.04` sits between the default `50` and `70`.'
                  value:
                    success: true
                    message: Face compare requires manual review
                    data:
                      similarityScore: 62.04
                    verificationStatus: REVIEW_NEEDED
                    verificationStatusCode: 2
                    transactionId: 7b3e9c14-2a68-4d05-91f7-6c8d0b2e4a31
                    verificationType: biometrics_face_compare
                    metadata:
                      customerReference: CUST-10294
                    createdAt: 2026-09-14 04:12:37+0000
                rejected:
                  summary: Faces do not match
                  value:
                    success: true
                    message: Face compare verification rejected
                    data:
                      similarityScore: 41.06
                    verificationStatus: REJECTED
                    verificationStatusCode: 1
                    transactionId: 7b3e9c14-2a68-4d05-91f7-6c8d0b2e4a31
                    verificationType: biometrics_face_compare
                    metadata:
                      customerReference: CUST-10294
                    createdAt: 2026-09-14 04:12:37+0000
        '400':
          description: >-
            Validation failed, a face could not be located, or an image could
            not be decoded. Nothing was compared; reserved credit is released
            and the call is not billed.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: >-
                      #/components/schemas/BiometricsFaceCompareValidationErrorResponse
                  - $ref: '#/components/schemas/BiometricsFaceCompareErrorResponse'
              examples:
                invalidRequest:
                  summary: Request failed validation
                  value:
                    success: false
                    code: VALIDATION_FAILED
                    message: >-
                      The request could not be validated. Please check the
                      submitted fields.
                    errors:
                      image2:
                        - The image2 field is required.
                      minSimilarityScore:
                        - The min similarity score must be between 0 and 100.
                    transactionId: null
                    verificationType: biometrics_face_compare
                    createdAt: 2026-09-14 04:12:37+0000
                noFaceFound:
                  summary: A face could not be located in one or both images
                  description: >-
                    Nothing was compared, so this is a failure rather than a
                    score of zero, and it is not billed.
                  value:
                    success: false
                    message: >-
                      No face found in one or both images. Please ensure that
                      the images contain a clear face.
                    data: {}
                    verificationStatus: FAILED
                    verificationStatusCode: 6
                    transactionId: 7b3e9c14-2a68-4d05-91f7-6c8d0b2e4a31
                    verificationType: biometrics_face_compare
                    metadata: null
                    createdAt: 2026-09-14 04:12:37+0000
                unusableImage:
                  summary: An image could not be decoded
                  description: >-
                    Other `message` values: `"image1 is required"` / `"image2 is
                    required"` when the field was present but empty; `"image1
                    must be an uploaded file or base64 image; URLs are not
                    supported."`; `"Failed to process image data for image2"`
                    when the value was not decodable image data.
                  value:
                    success: false
                    message: >-
                      image1 must be an uploaded file or base64 image; URLs are
                      not supported.
                    data: {}
                    verificationStatus: FAILED
                    verificationStatusCode: 6
                    transactionId: 7b3e9c14-2a68-4d05-91f7-6c8d0b2e4a31
                    verificationType: biometrics_face_compare
                    metadata: null
                    createdAt: 2026-09-14 04:12:37+0000
        '500':
          description: Unhandled failure. Reserved credit is released.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BiometricsFaceCompareErrorResponse'
              examples:
                internalError:
                  summary: Unhandled failure
                  value:
                    success: false
                    message: Internal Server Error
                    data: {}
                    verificationStatus: FAILED
                    verificationStatusCode: 6
                    transactionId: 7b3e9c14-2a68-4d05-91f7-6c8d0b2e4a31
                    verificationType: biometrics_face_compare
                    metadata: null
                    createdAt: 2026-09-14 04:12:37+0000
        '502':
          description: >-
            The face compare engine could not be reached. Reserved credit is
            released.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BiometricsFaceCompareErrorResponse'
              examples:
                sourceUnavailable:
                  summary: The face compare engine could not be reached
                  value:
                    success: false
                    message: Failed to process face compare verification
                    data: {}
                    verificationStatus: FAILED
                    verificationStatusCode: 6
                    transactionId: 7b3e9c14-2a68-4d05-91f7-6c8d0b2e4a31
                    verificationType: biometrics_face_compare
                    metadata: null
                    createdAt: 2026-09-14 04:12:37+0000
components:
  schemas:
    BiometricsFaceCompareRequest:
      type: object
      required:
        - image1
        - image2
      properties:
        image1:
          type: string
          description: >-
            Base64 data URI (for example `data:image/jpeg;base64,...`), or a
            multipart file upload when posting `multipart/form-data`. URLs are
            not accepted.
        image2:
          type: string
          description: >-
            The face to compare against, in the same accepted formats as
            `image1`. URLs are not accepted.
        minSimilarityScore:
          type: number
          minimum: 0
          maximum: 100
          default: 50
          description: >-
            Percentage (0–100). Similarity scores below this value are
            `REJECTED`
        verifiedSimilarityScore:
          type: number
          minimum: 0
          maximum: 100
          default: 70
          description: >-
            Percentage (0–100). Similarity scores at or above this value are
            `VERIFIED`. When the similarity score is between
            `minSimilarityScore` and `verifiedSimilarityScore`, the outcome is
            `REVIEW_NEEDED`.
        metadata:
          type: object
          additionalProperties: true
          description: Free-form correlation data, echoed back on the response.
    BiometricsFaceCompareSuccessResponse:
      type: object
      required:
        - success
        - message
        - data
        - verificationStatus
        - verificationStatusCode
        - transactionId
        - verificationType
        - createdAt
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        data:
          type: object
          required:
            - similarityScore
          properties:
            similarityScore:
              type: number
              minimum: 0
              maximum: 100
              description: >-
                Face similarity as a percentage (0–100), on the same scale as
                `minSimilarityScore` and `verifiedSimilarityScore`.
          additionalProperties: false
        verificationStatus:
          type: string
          enum:
            - VERIFIED
            - REVIEW_NEEDED
            - REJECTED
        verificationStatusCode:
          type: integer
          enum:
            - 3
            - 2
            - 1
          description: '`3` = Verified, `2` = Review Needed, `1` = Rejected.'
        transactionId:
          type: string
          format: uuid
        verificationType:
          type: string
          example: biometrics_face_compare
        metadata:
          type: object
          additionalProperties: true
          nullable: true
        createdAt:
          type: string
          example: 2026-09-14 04:12:37+0000
    BiometricsFaceCompareValidationErrorResponse:
      type: object
      required:
        - success
        - code
        - message
        - errors
        - transactionId
        - verificationType
        - createdAt
      properties:
        success:
          type: boolean
          example: false
        code:
          type: string
          enum:
            - VALIDATION_FAILED
        message:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        transactionId:
          type: string
          format: uuid
          nullable: true
        verificationType:
          type: string
          example: biometrics_face_compare
        createdAt:
          type: string
    BiometricsFaceCompareErrorResponse:
      type: object
      required:
        - success
        - message
        - verificationStatus
        - verificationStatusCode
        - transactionId
        - verificationType
        - createdAt
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
        data:
          type: object
          additionalProperties: true
          description: Empty object when present.
        verificationStatus:
          type: string
          example: FAILED
        verificationStatusCode:
          type: integer
          example: 6
        transactionId:
          type: string
          format: uuid
          nullable: true
        verificationType:
          type: string
          example: biometrics_face_compare
        metadata:
          type: object
          additionalProperties: true
          nullable: true
        createdAt:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Use your API token as a Bearer token in the `Authorization` header.

````