Cases | Verifa

A review case is created when a verification workflow routes to needs_review. Cases provide a structured review queue where your team can examine extracted data, documents, check results, and fraud signals before making a final decision.

Case lifecycle

open → in_review → approved
                 → rejected
                 → escalated → pending_second_review → approved
                                                     → rejected

Statuses

Status	Description
`open`	Unassigned. Waiting in the queue for a reviewer to claim.
`in_review`	Claimed by a reviewer. The reviewer has 30 minutes to act before the claim auto-releases.
`escalated`	Escalated to a senior reviewer or manager.
`pending_second_review`	First reviewer submitted a recommendation. Waiting for a second reviewer (dual-review).
`approved`	Final decision: approved.
`rejected`	Final decision: rejected.

Active statuses: open, in_review, escalated, pending_second_review

Final statuses: approved, rejected

SLA tracking

Cases track time from when they enter the review queue:

SLA	Time in queue	Urgency
Green	Less than 4 hours	On track
Yellow	Less than 24 hours	Approaching deadline
Red	24 hours or more	Overdue

Claiming and reviewing cases

Claim the next case

Atomically claim the next unassigned case from the queue (FIFO):

curl -X POST https://api.withverifa.com/api/v1/cases/next \
  -H "X-API-Key: vk_live_your_key_here"

Returns the full case with session data, documents, and check results. If no cases are available, returns 204 No Content.

Claim a specific case

curl -X POST https://api.withverifa.com/api/v1/cases/case_abc123/claim \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reviewer_id": "orguser_abc123"
  }'

Release a claim

If you can’t complete the review, release the case back to the queue:

curl -X POST https://api.withverifa.com/api/v1/cases/case_abc123/release \
  -H "X-API-Key: vk_live_your_key_here"

Claims auto-expire after 30 minutes of inactivity.

Making decisions

Approve

curl -X POST https://api.withverifa.com/api/v1/cases/case_abc123/approve \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reviewer_id": "orguser_abc123",
    "notes": "ID appears genuine. Face match is strong."
  }'

Reject

curl -X POST https://api.withverifa.com/api/v1/cases/case_abc123/reject \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reviewer_id": "orguser_abc123",
    "rejection_reason": "Document appears altered.",
    "notes": "Font inconsistency detected on name field."
  }'

Escalate

curl -X POST https://api.withverifa.com/api/v1/cases/case_abc123/escalate \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reviewer_id": "orguser_abc123",
    "reason": "Potential sanctions match requires compliance review.",
    "escalated_to": "usr_compliance_lead"
  }'

Dual-review workflows

For high-risk decisions, you can require two independent reviews. When dual review is enabled:

First reviewer claims and submits a recommendation (approve or reject)
Case moves to pending_second_review
A different reviewer claims and makes the final decision
The system enforces that the second reviewer is different from the first

Listing cases

curl "https://api.withverifa.com/api/v1/cases?status=open&limit=25" \
  -H "X-API-Key: vk_live_your_key_here"

Queue tab counts

Get badge counts for each queue tab:

curl https://api.withverifa.com/api/v1/cases/tab-counts \
  -H "X-API-Key: vk_live_your_key_here"

{
  "open": 12,
  "in_review": 3,
  "escalated": 1,
  "pending_second_review": 2,
  "approved": 456,
  "rejected": 89
}

Case notes

Add notes to a case for context and collaboration:

curl -X POST https://api.withverifa.com/api/v1/cases/case_abc123/notes \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Checked against internal records — name matches."
  }'

List notes:

curl https://api.withverifa.com/api/v1/cases/case_abc123/notes \
  -H "X-API-Key: vk_live_your_key_here"

Check overrides

Override a failed check within a case (e.g., approve despite a borderline face match):

curl -X POST https://api.withverifa.com/api/v1/cases/case_abc123/override/face_match \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Manual photo comparison confirms identity."
  }'

Overrides are recorded in the audit log with the reviewer’s identity and reason.

PII correction

Correct extracted PII during review (e.g., OCR misread a character):

curl -X PUT https://api.withverifa.com/api/v1/cases/case_abc123/result/pii \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "O'\''Brien"
  }'

Corrected PII is re-encrypted and the change is audit-logged.

Webhooks

Event	When
`case.created`	A new review case was created.
`case.claimed`	A reviewer claimed the case.
`case.approved`	The case was approved (final decision).
`case.rejected`	The case was rejected (final decision).

Sessions — How sessions trigger case creation
Workflows — Configure which conditions route to review
Identities — How case decisions update identity records