> For the complete documentation index, see [llms.txt](https://docs.vida.id/identity-stack/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vida.id/identity-stack/identity-operation-center/fraud-ops/liveness-fraud-ops/liveness-status-api.md).

# Liveness Status API

The Liveness Transaction Details API allows partners to get the Liveness detection result of Liveness API and Liveness SDK result. This can be done by using the unique transaction ID  which returned when invoking liveness API or from SDK liveness output. 

## Liveness API

<mark style="color:green;">`GET`</mark> `https://{vida.host}/biometrics/v2/services/face/liveliness?transactionId={UUID}`

#### Headers

| Name                                            | Type | Description                                                                                              |
| ----------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> |      | <p>OAuth access token. </p><p>Get the token by calling the</p><p><strong>Authentication</strong> API</p> |

### API Response

### Transaction Details Found Successfully

#### Case 1 : Liveness transacion completed successfully with scores below threshold.

HTTP Status Code: `200`

**JSON Response**

```json
{
    "data": {
        "transaction": {
            "transactionId": "edfc6404-9e63-4c75-b7a3-d0f27597661e",
            "transactionCode": 1043
        },
        "scores": [
            {
                "scoreName": "LIVENESS",
                "scoreValue": 0.910008
            },
            {
                "scoreName": "IMAGE_MANIPULATION",
                "scoreValue": 0.910211
            }
        ],
        "image": "Base64 image"
    }
}
```

#### Case 2 : Liveness transaction completed successfully with scores above threshold.

HTTP Status Code: `200`

**JSON Response**

```json
{
    "data": {
        "transaction": {
            "transactionId": "98d3e451-e966-4a61-9bd4-f8fcb935f04f",
            "transactionCode": 1041
        },
        "scores": [
            {
                "scoreName": "LIVENESS",
                "scoreValue": 0.999674
            },
            {
                "scoreName": "IMAGE_MANIPULATION",
                "scoreValue": 0.971477
            }
        ],
        "image": "Base64 image"
    }
}
```

#### Case 3 : Liveness transaction failed due to particular reason.

HTTP Status Code: `200`

**JSON Response**

```json
{
    "data": {
        "transaction": {
            "transactionId": "28b343d0-1479-4b00-bc73-5e16c95afa56",
            "transactionCode": 10001
        },
        "errors": [
            {
                "code": 1063,
                "title": "Image Quality Is Below Threshold",
                "detail": "Unnatural colour"
            },
            {
                "code": 1075,
                "title": "Image Quality Is Below Threshold",
                "detail": "Over Exposure"
            },
            {
                "code": 1076,
                "title": "Image Quality Is Below Threshold",
                "detail": "Image Is Blur"
            }
        ],
        "image": "Base64 image"
    }
}
```

### Transaction Details Not Found

HTTP Status Code: `404`

**JSON Response**

```json
{
    "transactionId": "48f93047-38cb-444d-b557-c72d8d6db185",
    "errors": [
        {
            "code": 1602,
            "title": "Transaction Not Found",
            "detail": "Transaction Not Found: 48f93047-38cb-444d-b557-c72d8d6db185"
        }
    ]
}
```

***

## Liveness Fraud Ops Transaction Details

VIDA Liveness Fraud Ops is a **near-real-time manual fraud review** system for VIDA liveness service. When your system accepts a user's liveness check based on VIDA’s automated evaluation, Fraud Ops **intercepts that session for deeper inspection** — especially when the session score passes the AI threshold but may still exhibit signs of spoofing.

When VIDA detects potential fraud through its **Fraud Ops**, by a specially-trained human, you can receive the notification via webhook, or actively **hit the Liveness Transaction Details API with added details.**

### API Endpoint

<mark style="color:green;">`GET`</mark> `https://{vida.host}/biometrics/v2/services/face/liveliness?transactionId={UUID}`

#### Headers

| Name                                            | Type | Description                                                                                              |
| ----------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> |      | <p>OAuth access token. </p><p>Get the token by calling the</p><p><strong>Authentication</strong> API</p> |

### API Response

```json
{
    "data": {
        "transaction": {
           ... //same format
        },
        "scores": [
           ... //same format
        ],
        "manualReview": {
            "ticketId": "01K06WXBN8JSG24E0GPADN1231",
            "assessment": "SPOOF",
            "reason": "Injection Attack-Face Manipulation"
        },
        "image": "<base64>"
    }
}
```

<table><thead><tr><th width="167.75390625">Field</th><th width="145.75">Type</th><th>Description</th></tr></thead><tbody><tr><td>manualReview</td><td>JSON Object</td><td>Details of manual review from the queried liveness transaction</td></tr><tr><td>ticketId</td><td>string</td><td>Unique reference ID to the manual review ticket, for auditing or support purpose</td></tr><tr><td>assessment</td><td>string</td><td>Result of the manual review by specially-trained human.<br><code>SPOOF</code> indicates a confirmed fraud by human agent</td></tr><tr><td>reason</td><td>string</td><td>Brief explanation of the attack and spoof type</td></tr></tbody></table>