2.0.0
Release date: May 25, 2026
Overview
Facephi IAD Service 2.0.0 is a major Version that introduces a new public REST contract for the Liveness and extraction flows. This Version is not backward-compatible with the 1.x.x series.
Breaking changes
Changes in the public endpoints
POST /api/v1/iad/check-capture
POST /api/v1/iad/liveness/evaluate
POST /api/v1/iad/extract-image
POST /api/v1/iad/extract
Changes in the multipart contract
Multipart requests now require the field
capture.Requests that include only the legacy field
filewithoutcaptureare rejected.
Changes in the success payload
Public success payloads now expose Facephi-style fields such as
diagnostic,reason,probability,score,faceProbability,sdkDurationandqueueDuration.Legacy Engine-shaped fields, such as
capture_liveness,capture_type,rejectionandmime_type, are no longer returned in public success responses.
What's new
Public contract normalization
Liveness responses are mapped to a stable public contract focused on Facephi Integration fields.
The public values of
reasonof Liveness are explicitly documented asNone,Unknown,UntrustedEnvironment,SuspiciousActivity,UntrustedDevice,SdkIntegrityViolation,UntrustedCorruptedPayload,UntrustedContentandUntrustedContentLowConfidence.Capture validation errors are normalized to Facephi/SelphID-style values.
Experimental mitigation against replay attacks
The service can apply a freshness window to incoming capture payloads.
Startup environment variables
FACEPHI_IAD_REPLAY_ATTACK_CHECKER_ENABLEDandFACEPHI_IAD_REPLAY_ATTACK_TOLERANCE_TIMEenable and configure the feature.The default freshness window is
300seconds.When the freshness window is exceeded, capture processing endpoints return HTTP
400withmessageequal toReplay attack detected.
Reliability and runtime behavior
Service startup failures propagate to
maininstead of terminating from the internal startup components.Signal handling no longer performs signal-unsafe operations, such as logging, shutdown logic, or
std::exit, directly from the handlers.
Quality assurance
Unit tests were added for public success payload mapping and prevention of private field leaks.
Unit tests were added to verify the behavior of the required multipart field
capture.
Migration guide (from 1.x.x)
Update the endpoint routes in client integrations.
Rename the multipart form field from
filetocapture.Update response parsing for successful Liveness requests so that they use the new public fields.
Validate the behavior of the integration with
GET /api/v1/iad/versionand end-to-end tests in your environment.
Deployment
Requirements
Operating system
Linux x86_64 (Ubuntu 24.04 is recommended)
License
Valid Facephi License file
Docker
For container deployment
Support
For Technical Support, contact your Facephi representative.
Documentation
Last updated