> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deepfake and impersonation detection

> Scan subjects for deepfake and impersonation indicators, review verdicts, and feed results into the risk signal pipeline automatically.

The deepfake and impersonation detection API lets you scan images, videos, documents, attestations, and identities for signs of manipulation or fraud. Scans that exceed the risk threshold automatically create a [risk signal](/guides/risk-signals), connecting detection directly to the Anti-Fraud Identity Firewall pipeline.

<Info>
  Deepfake detection is part of the [Anti-Fraud Identity Firewall](/guides/risk-signals). Scan results flow into the same risk signal pipeline as other fraud signals, so you can query and review them from the **Risk & Fraud > Signals** console page or the [list signals endpoint](/api-reference/risk-signals/list).
</Info>

## How it works

<Steps>
  <Step title="Submit a scan">
    Send a `POST` request to `/v1/risk/deepfake/scan` with a subject reference and either raw indicator signals from your detection pipeline or pre-computed scores from an external model.
  </Step>

  <Step title="Review the verdict">
    The response includes deepfake and impersonation scores (0–100) and a verdict: `authentic`, `suspect`, `deepfake`, or `impersonation`.
  </Step>

  <Step title="Automatic signal creation">
    When a score reaches 60 or above, the platform automatically ingests a risk signal into your tenant's pipeline. The response includes the `signal_id` so you can trace it.
  </Step>

  <Step title="Retrieve results later">
    Use `GET /v1/risk/deepfake/results/{subject_ref}` to fetch the latest scan result for any previously scanned subject.
  </Step>
</Steps>

## Prerequisites

* An active Truthlocks tenant with an API key
* Subject references for the content you want to scan (URLs, SHA-256 hashes, attestation IDs, or opaque identifiers)

## Scanning a subject

Submit a scan with indicator signals from your detection pipeline:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.truthlocks.com/v1/risk/deepfake/scan \
    -H "X-API-Key: tl_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "subject_ref": "sha256:a1b2c3d4...",
      "subject_type": "image",
      "signals": ["face_swap_detected", "inconsistent_lighting"]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.truthlocks.com/v1/risk/deepfake/scan", {
    method: "POST",
    headers: {
      "X-API-Key": "tl_live_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      subject_ref: "sha256:a1b2c3d4...",
      subject_type: "image",
      signals: ["face_swap_detected", "inconsistent_lighting"],
    }),
  });
  const result = await response.json();
  ```

  ```python Python theme={null}
  import httpx

  resp = httpx.post(
      "https://api.truthlocks.com/v1/risk/deepfake/scan",
      headers={"X-API-Key": "tl_live_..."},
      json={
          "subject_ref": "sha256:a1b2c3d4...",
          "subject_type": "image",
          "signals": ["face_swap_detected", "inconsistent_lighting"],
      },
  )
  result = resp.json()
  ```
</CodeGroup>

The response includes scores, a verdict, and (if the threshold was met) a linked risk signal:

```json theme={null}
{
  "scan_id": "7c8d9e0f-...",
  "subject_ref": "sha256:a1b2c3d4...",
  "subject_type": "image",
  "deepfake_score": 60,
  "impersonation_score": 0,
  "verdict": "suspect",
  "indicators": ["face_swap_detected", "inconsistent_lighting"],
  "detection_model": "heuristic_v1",
  "signal_id": "9f3a1c2d-...",
  "created_at": "2027-05-22T10:00:00Z"
}
```

## Detection model

The platform uses a heuristic signal engine (`heuristic_v1`) that maps caller-provided indicators to weighted scores. The engine evaluates 12 indicators across two categories:

### Deepfake indicators

| Indicator                | Description                                          |
| :----------------------- | :--------------------------------------------------- |
| `face_swap_detected`     | Face replacement or morphing detected                |
| `inconsistent_lighting`  | Lighting inconsistencies across the subject          |
| `compression_artifacts`  | Unusual compression patterns suggesting manipulation |
| `temporal_inconsistency` | Frame-level inconsistencies in video content         |
| `metadata_mismatch`      | File metadata doesn't match expected patterns        |

### Impersonation indicators

| Indicator                | Description                                       |
| :----------------------- | :------------------------------------------------ |
| `biometric_mismatch`     | Biometric data doesn't match the claimed identity |
| `name_mismatch`          | Name on identity document doesn't match records   |
| `identity_doc_mismatch`  | Identity document appears altered or inconsistent |
| `issuer_trust_violation` | Issuer trust level is insufficient for the claim  |

## Verdicts and thresholds

Each scan produces a verdict based on the highest score:

| Score range | Verdict                       | Meaning                                                                 |
| :---------- | :---------------------------- | :---------------------------------------------------------------------- |
| 0 – 39      | `authentic`                   | No significant indicators detected                                      |
| 40 – 74     | `suspect`                     | Some indicators present — review recommended                            |
| 75 – 100    | `deepfake` or `impersonation` | High confidence detection — which verdict depends on the dominant score |

When either score reaches **60 or above**, the platform automatically creates a risk signal. You don't need to make a separate API call — the `signal_id` is returned in the scan response.

## Using pre-computed scores

If you already have scores from an external ML model or detection service, pass them directly to skip heuristic analysis:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/risk/deepfake/scan \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "subject_ref": "sha256:a1b2c3d4...",
    "subject_type": "video",
    "deepfake_score": 82,
    "impersonation_score": 15
  }'
```

The platform still applies the same verdict thresholds and automatic signal ingestion, so you get consistent classification regardless of the detection source.

## Linking scans to attestations

Associate a scan with an existing attestation to tie detection results to the credential they relate to:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/risk/deepfake/scan \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "subject_ref": "sha256:a1b2c3d4...",
    "subject_type": "attestation",
    "signals": ["biometric_mismatch", "identity_doc_mismatch"],
    "attestation_id": "660e8400-e29b-41d4-a716-446655440001"
  }'
```

This makes it easier to flag and review suspicious attestations in the console.

## Retrieving scan results

Fetch the latest scan result for a subject without re-running the scan:

```bash theme={null}
curl https://api.truthlocks.com/v1/risk/deepfake/results/sha256:a1b2c3d4... \
  -H "X-API-Key: tl_live_..."
```

## Subject types

The `subject_type` field tells the platform what kind of content is being scanned:

| Type          | Use case                                |
| :------------ | :-------------------------------------- |
| `image`       | Photos, ID documents, profile pictures  |
| `video`       | Video recordings, live captures         |
| `document`    | PDFs, scanned documents                 |
| `attestation` | Credentials issued through the platform |
| `identity`    | Identity claims, KYC submissions        |

## Usage metering

Each deepfake scan request increments the `antifraud.deepfake_scans` usage counter for your billing cycle. You can monitor your scan consumption with the [usage API](/api-reference/billing/usage) or in the console at **Settings > Billing > Usage** under the **Anti-Fraud** section.

<Info>
  Deepfake scan quotas vary by plan tier. See the [billing overview](/billing/overview#metered-products) for details on all Anti-Fraud metered products.
</Info>

## What's next

* [Deepfake scan API reference](/api-reference/risk/deepfake-scan)
* [Get scan results API reference](/api-reference/risk/deepfake-results)
* [Account takeover detection guide](/guides/ato-detection)
* [Velocity and anomaly scoring guide](/guides/velocity-scoring)
* [Risk signals guide](/guides/risk-signals)
* [Ingest risk signal API reference](/api-reference/risk/ingest-signal)