Interpreting responses

The first-level fields

Field	What it is
`id`	The transaction identifier. Always log it: it is the first thing support asks for.
`info`	Your reference, echoed back verbatim.
`code` / `message`	The global result: `200` / `Operation end successfully`.
`biometric`	The 0–100 similarity matrix. The field to decide on.
`confidences`	A duplicate of `biometric` kept for backwards compatibility. Do not read it.
`faceLocation`	The bounding box of the detected face in each image, in pixels. Informational.
`faceFeatures`	The 16 attributes scored 0–100, if requested.
`headPoseEstimation`	The pose in degrees, if requested.
`inferenceConfidence`	The aggregated quality verdict. Always present, in two different shapes — see below.
`antiSpoofingFace`	The antispoofing service’s response, nested, if requested.
`faceVector`	The 512-value vector per face, if you sent `returnFaceVector`.
`faceImage`	The aligned face crop in base64, if you sent `returnFaceImage`.
`benchmark`	Internal processing time. It is not a score: do not decide on it.

Result keys are strings

Every result block is indexed by image number as JSON text: "0", "1"… The biometric matrix is body.biometric["0"]["1"], not [0][1]. In typed languages, deserialize as Map<String, …>.

{
  "biometric": {
    "0": { "0": 100, "1": 93 },
    "1": { "1": 100, "0": 93 }
  }
}

The diagonal ("0" vs "0") is always 100: it is each face against itself. If you also sent faceVectors, the vectors continue the numbering after the images: 1 image + 1 vector ⇒ keys "0" (the image) and "1" (the vector). Reference values measured with vu_v4 on the team’s test photos: same person ≈ 93–95 · different people ≈ 19. With the same two photos, cosine yields 78 and euclidean_l2 yields 66: never compare scores across methodologies.

`inferenceConfidence` changes shape

It appears for every image, always, but in two shapes:

Shape	When
`{"message": "...", "code": 200 \| 202 \| 406, "confidence": "high" \| "medium" \| "low"}`	You requested `faceFeatures` and `headPoseEstimation` together, or the image is under 360 px.
`{"message": "headPoseEstimation and faceFeatures need to be enabled..."}` — no `code`, no `confidence`	Any other case.

Type code and confidence as optional. The mapping is fixed: 200 = high, 202 = medium, 406 = low.

Do not confuse levels. The code: 406 nested inside inferenceConfidence does not change the HTTP code or the first-level code, which stay 200. A low-quality image is not an API error: it is a signal to ask the user for another capture.

What degrades the verdict: face mask, closed eyes, blur, non-frontal pose, extreme makeup, and — automatically — any image under 360 px on a side.

The 16 `faceFeatures` attributes

Each attribute is a 0–100 score where higher = more present: blurry, eyeglasses, sunglasses, faceMask, leftEyeClosed, rightEyeClosed, mouthOpen, beard, mustache, smiling, heavyMakeup, hat, earrings, necklace, necktie, lipstick. Use them to guide the user (“please remove your sunglasses”), not as identity conditions. headPoseEstimation carries the pose in degrees: leftRight (yaw) and upDown (pitch). Zero is perfectly frontal; a face useful for biometrics usually sits within ±15°.

The antispoofing comes nested, with its own scale

antiSpoofingFace["0"] contains the full response of the Facial Antispoofing service, nested as-is:

{
  "antiSpoofingFace": {
    "0": {
      "code": 200,
      "spoofing": false,
      "confidence": 99.2
    }
  }
}

Decide on its spoofing field (boolean). Do not decide on its inner code or confidence: they carry the antispoofing service’s semantics, not Face Analysis’s.

If the antispoofing service does not respond, antiSpoofingFace["0"] arrives as null and the rest of the response is still 200. Treat null as “no verdict” — never as an approval.

Deserializer particularities

Result blocks are indexed by string ("0", "1"), not by integer.
inferenceConfidence has two shapes: code and confidence are optional.
antiSpoofingFace[i] can be an object or null.
confidences duplicates biometric: ignore it, but do not fail when it appears.
With faceVectors, result numbering includes the vectors after the images.
The 500s arrive with a plain-text body, not JSON — see Errors.

Next: Errors

Error codes, the plain-text 500s, the batch abort with imageNumber, and what to retry.

Start here

ID Analysis

Face Analysis

Facial Antispoofing

Connection Fingerprint

The first-level fields

Result keys are strings

`inferenceConfidence` changes shape

The 16 `faceFeatures` attributes

The antispoofing comes nested, with its own scale

Deserializer particularities

Next: Errors

​The first-level fields

​Result keys are strings

​inferenceConfidence changes shape

​The 16 faceFeatures attributes

​The antispoofing comes nested, with its own scale

​Deserializer particularities

Next: Errors

The first-level fields

Result keys are strings

`inferenceConfidence` changes shape

The 16 `faceFeatures` attributes

The antispoofing comes nested, with its own scale

Deserializer particularities