Evaluate liveness

Verifies liveness on an encrypted biometric capture and exposes a public Facephi result. The multipart request field name must be capture; the legacy file field is not accepted.

Successful HTTP 200 responses return the public fields diagnostic, reason, probability, score, sdkDuration and queueDuration.

If the experimental replay attack mitigation is enabled at deployment time, captures older than the configured validity window are rejected with HTTP 400 and the message Replay attack detected.

post

Body

capturestring · binaryRequired

Binary data buffer, typically biometric capture data (images, video frames, etc.).

Responses

200

Public liveness result

application/json

Public liveness response exposed by the Facephi API.

diagnosticstring · enumOptionalPossible values:

reasonstring · enumOptional

Public liveness reason.

Possible values:

• None: the capture was accepted as Live.
• Unknown: the service could not map the response to a documented public rejection reason.
• UntrustedEnvironment: the execution environment is not considered trustworthy.
• SuspiciousActivity: the device showed activity patterns associated with an attack.
• UntrustedDevice: the device could not be trusted to be what it claims to be.
• SdkIntegrityViolation: the capture SDK or its libraries appear to have been tampered with.
• UntrustedCorruptedPayload: the payload appears to be corrupted or tampered with.
• UntrustedContent: an injection attack was detected.
• UntrustedContentLowConfidence: signs of an injection attack were detected with lower confidence and the capture must still be treated as rejected.

Example: UntrustedContentPossible values:

probabilitynumber · floatOptionalExample: 1

scorenumber · floatOptionalExample: 1

faceProbabilitynumber · floatOptionalExample: 0.9969

sdkDurationinteger · int64OptionalExample: 12

queueDurationinteger · int64OptionalExample: 3

400

Request validation error or capture validity validation error.

Capture validation errors are normalized in the public message field.

application/json

500

An error occurred in the backend.

application/json

post/api/v1/iad/liveness/evaluate

POST /api/v1/iad/liveness/evaluate HTTP/1.1
Host: 127.0.0.1:6982/
Content-Type: multipart/form-data
Accept: */*
Content-Length: 20

{
  "capture": "binary"
}

{
  "diagnostic": "Live",
  "reason": "None",
  "probability": 1,
  "score": 1,
  "sdkDuration": 12,
  "queueDuration": 3
}