Skip to main content
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, connecting detection directly to the Anti-Fraud Identity Firewall pipeline.
Deepfake detection is part of the Anti-Fraud Identity Firewall. 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.

​
How it works

1

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.
2

Review the verdict

The response includes deepfake and impersonation scores (0–100) and a verdict: authentic, suspect, deepfake, or impersonation.
3

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.
4

Retrieve results later

Use GET /v1/risk/deepfake/results/{subject_ref} to fetch the latest scan result for any previously scanned subject.

​
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: 
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"]
  }'
The response includes scores, a verdict, and (if the threshold was met) a linked risk signal: 
{
  "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

IndicatorDescription
face_swap_detectedFace replacement or morphing detected
inconsistent_lightingLighting inconsistencies across the subject
compression_artifactsUnusual compression patterns suggesting manipulation
temporal_inconsistencyFrame-level inconsistencies in video content
metadata_mismatchFile metadata doesn’t match expected patterns

​
Impersonation indicators

IndicatorDescription
biometric_mismatchBiometric data doesn’t match the claimed identity
name_mismatchName on identity document doesn’t match records
identity_doc_mismatchIdentity document appears altered or inconsistent
issuer_trust_violationIssuer trust level is insufficient for the claim

​
Verdicts and thresholds

Each scan produces a verdict based on the highest score:
Score rangeVerdictMeaning
0 – 39authenticNo significant indicators detected
40 – 74suspectSome indicators present — review recommended
75 – 100deepfake or impersonationHigh 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: 
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: 
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: 
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:
TypeUse case
imagePhotos, ID documents, profile pictures
videoVideo recordings, live captures
documentPDFs, scanned documents
attestationCredentials issued through the platform
identityIdentity 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 or in the console at Settings > Billing > Usage under the Anti-Fraud section.
Deepfake scan quotas vary by plan tier. See the billing overview for details on all Anti-Fraud metered products.

​
What’s next