POST /api/v1/verify

Compliance & analyst path. Images and PDFs with the full presentation layer — evidence lifecycle, lineage-driven HITL, and export-ready forensic detail for regulated workflows.

Choose this when: MLRO/compliance needs custody artifacts, analysts read forensic_view, or lineage must force review on an otherwise-clean file. See endpoint comparison on the overview.

POST /api/v1/verify
Content-Type: multipart/form-data
Authorization: Bearer {api_key}

Input (multipart)

Field	Required	Description
`image`	one of image / image_url	File upload — JPEG, PNG, HEIC, WebP, or PDF
`image_url`	one of image / image_url	Public HTTPS URL to same formats
`detail_level`	no	`basic` (fast) or `detailed` (full EXIF + PDF phases). Default: `basic`
`preserve_exif`	no	`true` if bytes still carry EXIF (document upload). Default: `false`
`document_type`	no	Hint: `passport`, `bank_statement`, `utility_bill`, … Enables ID barcode checks on PDFs
`source`	no	Platform hint: `linkedin`, `telegram`, …
`product_source`	no	Caller id for telemetry. Default: `fraudlens_api`
`force_reanalyze`	no	Skip UFID cache, run fresh analysis
`agent_fast`	no	Deprecated. PDF: same as `pdf_mode=structural`
`pdf_mode`	no	PDF only: `metadata_fast` \| `structural` \| `full` (default `full`). Response echoes `pdf_mode` + `model` (e.g. `plica_pdf/structural/v1`)
`generate_narrative`	no	PDF only: async LLM narrative over structured container findings (default `false`)
`include_vision`	no	Reserved paid tier — not used in v1

Document scan images (JPEG / PNG)

Messaging-app scans (sterile EXIF, flat uploads) need explicit document routing:

Set preserve_exif=true when the uploaded bytes still carry metadata (direct file upload, not re-encoded in-browser). This enables document_fraud_hint — full tamper bundle, Layer 1 maps, and sterile EXIF copy (METADATA_STERILE as review, not camera-fraud fail).
detail_level=detailed recommended for onboarding document scans (~5–6s with Layer 1).
Optional document_type (e.g. utility_bill, id_card) — echoed in reports; enables barcode cross-check on ID PDFs only.

curl -s -X POST "https://api.plicaforensic.com/api/v1/verify" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@scan.jpg" \
  -F "detail_level=detailed" \
  -F "preserve_exif=true" \
  -F "document_type=utility_bill"

Modes

Images

basic — ~1–3s: intrinsic + key signals
detailed — ~5–10s: full EXIF validation, metadata reason codes

PDFs

PDF analysis is two-layer — not a single thumbnail check:

Container forensics — structure, revisions, OCR/text layer, XObjects, math checks (details.pdf_container, forensic_view.pdf_container).
Embedded rasters — JPEG/PNG extracted from page content; pixel forensics run on selected images and merge into composite embedded score.

Which raster is verified? Default mode (pdf_mode=full): the largest embedded raster by pixel area (largest_only). Fragment mode (heavy XObject splitting): up to 12 fragments. This is independent of visual order in the PDF. Container signals remain primary for text/template edits.

Downloaded forensic PDF reports reference the source PDF file in “Analyzed Evidence” — they do not embed a raster preview of an extracted page image.

metadata_fast — Creator/Producer + AI fingerprints only (~<2s)
structural — full container Phase 1, no embedded pixel (~3–5s). Legacy: agent_fast=true
full — Phase 1 + Phase 2 (when detailed) + embedded raster forensics (~8–12s)

Limits & quotas

Limit	PLICA	Notes
Max PDF upload	50 MB	Multi-page container forensics on full document
Max image upload	20 MB	JPEG, PNG, HEIC, WebP
Offline evidence verify	FEM + Packet Analyzer	PLICA-only offline path

PDF container fields (top-level)

PDF responses include integrator-friendly fields alongside details.pdf_container and forensic_view.pdf_container:

container_hit — true when any structure signal is flagged or AI metadata fingerprint matched
container_signals_flagged — count of flagged keys in structure.signals
estimated_credits — billing estimate (see credit table below)
details.pdf_container.container_label — No Tampering Detected | Review for Possible Tampering | Tampering Detected
details.pdf_container.tool_attribution — when AI export detected: tool, confidence, matched_field (creator/producer); otherwise null
details.pdf_container.structure.signals — core keys overlay, hidden, font, revision plus PLICA extensions ocr_mismatch, metadata_edit, math_logic
details.pdf_container.narrative_status — skipped (default), pending, ready, or failed
details.pdf_container.narrative_explanation — human paragraph when narrative_status=ready (not cryptographic proof)

Set generate_narrative=true on PDF uploads to enqueue async narrative (LLM over structured findings only). Poll job status or re-fetch analysis until narrative_status=ready.

Operation	Credits
Image `basic`	1
Image `detailed`	3
PDF `metadata_fast`	1
PDF `structural`	2 × pages
PDF `full`	5 × pages

Detection stack (summary)

Definitive proof — AI tool markers, temporal paradoxes, C2PA where present
Evidence scoring — weighted EXIF / metadata signals
Intrinsic forensics — pixel-level (works without metadata)
Layer 1 maps — localized edit candidates on document scans (tamper_regions)
PDF container — editing software, incremental updates, text/OCR anomalies
Lineage — XMP ID cross-submission signals → review escalation

Example (Python)

import requests

with open("statement.pdf", "rb") as f:
    r = requests.post(
        "https://api.plicaforensic.com/api/v1/verify",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        files={"image": ("statement.pdf", f, "application/pdf")},
        data={
            "detail_level": "detailed",
            "document_type": "bank_statement",
        },
        timeout=120,
    )
    r.raise_for_status()
    result = r.json()
    print(result["verdict"], result["fraud_score"])
    print(result["analyst_summary"]["verdict_tier"])

Related endpoints

GET /api/v1/verify/{analysis_id}/policy-actions — fetch actions for dispatch
POST /api/v1/verify/{analysis_id}/policy-actions/dispatch — send to configured webhook