For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
  • Getting Started
    • Introduction
    • How Verifa Works
    • Quickstart
    • Choosing an Integration Method
  • Use Cases
    • KYC Onboarding
    • Age Verification
    • AML Compliance
    • Fraud Prevention
    • Marketplace Trust & Safety
  • Core Concepts
    • Overview
    • Sessions
    • Verifications & Checks
    • Workflows
    • Identities
    • Cases
    • Screening & Reports
    • Lists
  • Integration Guides
    • Overview
    • JavaScript SDK
    • Web Capture Flow
    • API-Only Integration
    • Mobile SDK
    • Webhooks Guide
    • MCP Server
    • Migrating from Persona
  • API Details
    • Overview
    • Authentication
    • Pagination
    • Rate Limiting
    • Versioning
    • Errors
    • Webhooks
    • Idempotency
    • Key Inflection
    • Data Access
    • Data Retention
  • Tutorials
    • Creating Your First Verification Session
    • Creating a Workflow
    • Receiving Webhooks & Validating Signatures
    • Handling Webhook Events
    • Custom Document Types & AI Extraction
  • Best Practices
    • Testing
    • Preventing Duplicates
    • Fraud Signals
    • Changelog
  • API Reference
      • GETList my consortiums
      • GETGet consortium detail
      • GETList consortium matches
      • GETGet match detail
      • PATCHUpdate match status
      • GETList fraud rings
      • GETGet fraud ring detail
API ReferenceConsortiums

Update match status

PATCH
https://devapi.withverifa.com/api/v1/consortiums/:consortium_id/matches/:match_id
PATCH
/api/v1/consortiums/:consortium_id/matches/:match_id
$curl -X PATCH https://devapi.withverifa.com/api/v1/consortiums/consortium_id/matches/match_id \
>     -H "X-API-Key: <apiKey>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "status": "under_investigation"
>}'
1{
2  "id": "cm_7f8e9d2a",
3  "consortium_id": "cons_12345abcde",
4  "match_type": "face_and_document",
5  "status": "under_investigation",
6  "created_at": "2024-04-07T09:15:00Z",
7  "face_similarity_score": 0.87,
8  "name_mismatch": false,
9  "dob_mismatch": false,
10  "document_type_mismatch": false,
11  "document_number_match": true,
12  "email_match": false,
13  "phone_match": true,
14  "device_match": false,
15  "days_between": 3,
16  "ghost_student_score": 75,
17  "ghost_student_tier": "review",
18  "primary_session_id": "sess_98765xyz",
19  "primary_org_id": "org_00123",
20  "matched_session_id": "sess_54321abc",
21  "matched_org_id": "org_00456",
22  "primary_org_name": "Northside University",
23  "matched_org_name": "East Valley College",
24  "investigated_by": "jane.doe@northside.edu",
25  "investigated_at": "2024-04-10T14:45:00Z",
26  "resolution_notes": "Initial review started, awaiting further documentation.",
27  "updated_at": "2024-04-10T14:45:00Z"
28}

Update the investigation status of a consortium match. Terminal statuses (confirmed_fraud, false_positive, resolved) trigger a consortium.match_resolved webhook to both organizations involved.

Setting status to confirmed_fraud automatically triggers fraud ring detection via BFS traversal of connected sessions.

Was this page helpful?
Previous

List fraud rings

Next
Built with

Authentication

X-API-Keystring

Organization API key. Keys are prefixed with vk_live_ (production) or vk_sandbox_ (sandbox).

Path parameters

consortium_idstringRequired
match_idstringRequired

Headers

Verifa-VersiondateOptional

API version date string (e.g. 2026-02-01). If omitted, the version pinned to your API key is used.

Key-InflectionenumOptionalDefaults to snake

Response key casing. Defaults to snake.

Allowed values:

Request

This endpoint expects an object.
statusenumRequired
Allowed values:
resolution_notesstring or nullOptional
Optional notes about the investigation outcome.

Response

Updated match.
idstring
consortium_idstring
match_typeenum
Allowed values:
statusenum
Allowed values:
created_atdatetime
face_similarity_scoredouble or null

Cosine similarity between face embeddings (0–1).

name_mismatchboolean
True if the names on the two sessions differ.
dob_mismatchboolean
True if the dates of birth differ.
document_type_mismatchboolean
document_number_matchboolean
True if the same document number appears at both orgs.
email_matchboolean
phone_matchboolean
device_matchboolean
days_betweeninteger or null
Days between the two sessions' creation dates.
ghost_student_scoreinteger or null

Composite fraud risk score (0–100).

ghost_student_tierenum

Risk tier derived from ghost_student_score.

Allowed values:
primary_session_idstring or null

Present when sharing_level is “match_details” or higher.

primary_org_idstring or null
matched_session_idstring or null
matched_org_idstring or null
primary_org_namestring or null
matched_org_namestring or null
investigated_bystring or null
investigated_atdatetime or null
resolution_notesstring or null

Present when sharing_level is “full_investigation”.

updated_atdatetime

Errors

401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error