Case Management & Review

When a verification needs a human decision, the API opens a review case and routes it to your review queue. Reviewers then claim the case, inspect the session (including a tamper-evident evidence bundle), and record a decision.

Sessions are flagged for review when they fail or warn (and can be routed to manual review explicitly via flows).

Flag values

Flag	Meaning
fail	The session failed a required check
warn	The session passed but with a warning worth a look
pass	Passed (a case is not opened for these)
manual	Explicitly routed to manual review

Case lifecycle

open → claimed → decided.

List the queue

GET /admin/reviews?status=open&limit=100

curl -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  "https://api.dev.valydar.com/admin/reviews?status=open"

Response:

{
  "cases": [
    {
      "id": "rev_...",
      "verification_id": "vry_...",
      "flag": "fail",
      "reason": "liveness check failed",
      "status": "open",
      "reviewer": null,
      "decision": null,
      "decision_note": null,
      "created_at": "2026-09-26T12:00:00Z"
    }
  ]
}

Filter with ?status= (open | claimed | decided).

Inspect a case

GET /admin/reviews/{id}

Returns the case plus its append-only audit trail (flagged, claimed, decided) and the linked verification (session context):

{ "case": { }, "audit": [ ], "verification": { "status": "...", "checks_results": { } } }

Claim

POST /admin/reviews/{id}/claim

Marks the case claimed and records who took it. 400 if the case is not open.

Decide

POST /admin/reviews/{id}/decision

curl -X POST https://api.dev.valydar.com/admin/reviews/rev_.../decision \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"decision": "approved", "note": "verified against source"}
'

Decision	Meaning
approved	The session is accepted
rejected	The session is refused
refuted	The initial flag is overturned

Recording a decision fires a review.decided webhook to the session's client (see Webhooks).

Evidence bundle

GET /admin/reviews/{id}/evidence            # JSON manifest
GET /admin/reviews/{id}/evidence?format=pdf # printable PDF

When a verification completes, the SHA-256 of every captured artifact is frozen. The evidence endpoint recomputes the digests from the bytes currently stored and reports any artifact that no longer matches — proving whether evidence was altered after capture:

{
  "verified": false,
  "algorithm": "sha256",
  "artifacts": [
    {
      "artifact_id": "doc_...",
      "kind": "passport",
      "status": "modified",
      "stored_sha256": "1ad0…",
      "current_sha256": "aae9…"
    }
  ],
  "tampered": ["doc_..."],
  "bundle_sha256": "..."
}

Status	Meaning
verified	Current bytes match the digest captured at completion
modified	The artifact still exists but its bytes changed
missing	A captured artifact is no longer stored
untracked	An artifact exists now that was never captured

verified is true only when every artifact verifies. bundle_sha256 is a stable digest over the whole manifest (equal content ⇒ equal hash). format=pdf returns a printable, paginated manifest.

Admin review console

A minimal web console is available at GET /admin/ui (Review Queue tab) for listing cases, viewing context + audit, claiming/deciding, and downloading evidence.

Permissions

All /admin/reviews* endpoints require the reviews:manage permission (admin keys).