> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/iad/release_notes/2.0.0_release_notes.md).

# 2.0.0

**Release date:** May 25, 2026

## Overview

**Facephi IAD Service 2.0.0** is a major release that introduces a new public REST contract for evaluation and extraction flows. This version **is not backward compatible** with the 1.x.x series.

## Breaking Changes

### Changes to public endpoints

| Endpoint 1.x.x                   | Endpoint 2.0.0                       |
| -------------------------------- | ------------------------------------ |
| `POST /api/v1/iad/check-capture` | `POST /api/v1/iad/liveness/evaluate` |
| `POST /api/v1/iad/extract-image` | `POST /api/v1/iad/extract`           |

### Changes to the multipart contract

* Multipart requests now require the `capture`.
* Requests that include only the legacy `file` without `capture` field are rejected.

### Changes to the success payload

* Public success payloads now expose Facephi-style fields such as `diagnostic`, `reason`, `probability`, `score`, `faceProbability`, `sdkDuration` and `queueDuration`.
* Legacy Engine-shaped fields, such as `capture_liveness`, `capture_type`, `rejection` and `mime_type`, are no longer returned in public success responses.

## What's New

### Public contract normalization

* Evaluation responses are mapped to a stable public contract centered on Facephi integration fields.
* The public values for `reason` are explicitly documented as `None`, `Unknown`, `UntrustedEnvironment`, `SuspiciousActivity`, `UntrustedDevice`, `SdkIntegrityViolation`, `UntrustedCorruptedPayload`, `UntrustedContent` and `UntrustedContentLowConfidence`.
* Capture validation errors are normalized to Facephi/SelphID-style values.

### Experimental replay attack mitigation

* The service can apply a freshness window to incoming capture payloads.
* The startup environment variables `FACEPHI_IAD_REPLAY_ATTACK_CHECKER_ENABLED` and `FACEPHI_IAD_REPLAY_ATTACK_TOLERANCE_TIME` enable and configure this functionality.
* The default freshness window is `300` seconds.
* When the freshness window is exceeded, the capture processing endpoints return HTTP `400` with `message` equal to `Replay attack detected`.

### Reliability and runtime behavior

* Service startup failures are propagated to `main` instead of terminating from internal startup components.
* Signal handling no longer performs operations that are unsafe in signal handlers, 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)

1. Update the endpoint paths in client integrations.
2. Rename the multipart form field from `file` to `capture`.
3. Update response parsing for successful evaluation requests to use the new public fields.
4. Validate the integration behavior with `GET /api/v1/iad/version` and end-to-end tests in your environment.

## Deployment

```bash
docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-iad-service:2.0.0

docker run -d \
  -p 6982:6982 \
  -v /path/to/license:/app/license \
  -v /path/to/config:/app/config \
  --name iad-service \
  facephicorp.jfrog.io/docker-pro-fphi/facephi-iad-service:2.0.0
```

## Requirements

| Component        | Requirement                              |
| ---------------- | ---------------------------------------- |
| Operating system | Linux x86\_64 (Ubuntu 24.04 recommended) |
| License          | Valid Facephi license file               |
| Docker           | For container deployments                |

## Support

For Technical Support, contact your Facephi representative.

## Documentation

* [Configuration Reference](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/iad.md)
* [Installation Guide](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/iad/installation/installation_instructions.md)
* [API Reference](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/iad/technical_documentation/api_reference.md)
* [Changelog](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/iad/changelog.md)
