> 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

## General 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 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 in the multipart contract

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

### Changes in 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

* Liveness responses are mapped to a stable public contract focused on Facephi Integration fields.
* The public values of `reason` liveness 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 (replay)

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

### Reliability and runtime behavior

* Service startup failures propagate to `main` instead 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 preventing 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. Change the multipart form field name from `file` to `capture`.
3. Update response parsing for successful liveness requests so that they 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 deployment                 |

## Support

For Technical Support, contact your Facephi representative.

## Documentation

* [Configuration reference](/docs.facephi-en/sdks/backend-sdk/iad.md)
* [Installation guide](/docs.facephi-en/sdks/backend-sdk/iad/installation/installation_instructions.md)
* [API reference](/docs.facephi-en/sdks/backend-sdk/iad/technical_documentation/api_reference.md)
* [Changelog](/docs.facephi-en/sdks/backend-sdk/iad/changelog.md)