BrandKwikID Documentation
API SuiteFace & Biometrics (ML)

Advanced Facematch

Structured 1-photo or 2-photo flow — per-image liveness plus optional face match. POST /advanced_facematch with Bearer auth.

API reference

Try itLoading playground…
Loading…

Authorization

AuthorizationBearer <token>

JWT Bearer token authentication. Obtain a token from the KwikID dashboard.

In: header

Request Body

image1string
image2?string
unique_id?string

Optional correlation id for logs.

Response Body

curl -X POST "https://__mock__/advanced_facematch" \  -F image1="string"

{
  "image1": {
    "input_provided": "True",
    "result": "real",
    "confidence": 95,
    "prediction_confidence": 95
  },
  "image2": {
    "input_provided": "True",
    "result": "real",
    "confidence": 93.5,
    "prediction_confidence": 93.5
  },
  "image1_image2_facematch": {
    "performed": "True",
    "result": "True",
    "confidence": 87.2
  },
  "overall_result": "True",
  "overall_confidence": 91.82
}
{
  "msg": "string"
}
{
  "detail": {},
  "message": "string"
}

Overview

Call POST /advanced_facematch with Authorization: Bearer <token> (same scope as Facematch) and multipart/form-data. image1 is always required.** image2 is optional.

  • image1 only: Runs liveness (presentation attack check) on the first photo. image2 and image1_image2_facematch are filled with N/A / null / "False" as appropriate so the shape stays the same across modes.
  • image1 + image2: Runs liveness on each photo, then runs face match (pairwise comparison). overall_result is "True" only when both are real and the comparison is "True". Otherwise overall_result is "False" and overall_confidence is 0.

Deployments that mount SUMI v1 beneath an app prefix often use .../sumi/v1/advanced_facematch (your gateway prefix may differ).

Flow at a glance

Illustrative only — no implementation or model detail. Each liveness step is what fills image1.result / image2.result (real vs fake). The final face match step fills image1_image2_facematch when image2 is present.

confidence vs prediction_confidence (image blocks)

For image1 and image2, when result is fake, confidence is 0. The numeric score prior to that rule is returned as prediction_confidence when the service computed one; otherwise null.

200 response: keys, definitions, examples

Strings "True" / "False" are JSON strings, not booleans. Examples reflect a plausible two-image success path; other modes leave many fields "N/A" or null.

Response keyDefinitionExample value
image1.input_providedAlways "True" when the request validated image1."True"
image1.resultreal or fake from the presentation check on photo 1."real"
image1.confidenceScore surfaced for photo 1; 0 when fake.95.0
image1.prediction_confidenceRaw score before spoof zeroing; null if not applicable.95.0 or null
image2.input_provided"True" if image2 was sent and used; "False" in photo 1 only flow."True"
image2.resultreal, fake, or N/A if no second photo."real"
image2.confidenceScore for photo 2; null if no input; 0 when fake.93.5
image2.prediction_confidenceRaw score for photo 2; null if not computed.93.5 or null
image1_image2_facematch.performed"True" if both images were compared; "False" if image2 missing."True"
image1_image2_facematch.result"True" / "False" from comparison, or "N/A"."True"
image1_image2_facematch.confidenceMatch strength 0–100 (percent) when performed; null otherwise.87.2
overall_result"True" only if every active gate passes."True"
overall_confidence0–100 on success path; 0 when overall_result is "False".91.82

Key features

  • One contract, two workflows: Same response shape whether you send one or two images.
  • Clear separation: Per-image outcomes and optional pairwise image1_image2_facematch in one payload.

Bulk testing in the Playground

The Playground on this page supports Bulk (ZIP batch) mode. Screenshots, naming rules, Run, completion download, and output archive layout are documented on Facematch:

Switch this page’s Playground to Bulk and follow the same flow; shape your ZIP inputs to match POST /advanced_facematch (see OpenAPI on this page).

Implementation

Step 1: Call from your backend

Send multipart/form-data with image1 plus optional image2 file parts and optional unique_id.

Error handling

HTTP statusWhen
400Empty image1, bad format, size outside limits (~1 KB–10 MB), no face usable in an image, or other processing failure (often msg in JSON).
401Invalid token.

Benefits

  • Aligns structured reporting with richer risk and audit UX than flat facematch_result alone when you need per-image context.

Facematch POST

Compare two face images and return a match score. Server-side multipart POST with Bearer auth; binary image1 and image2.

Index Faces (Rekognition) POST

Index a face into the AWS Rekognition collection via JSON — image, bucket, image_key, external_image_id. POST /index_faces with Bearer auth.