Update match status

PATCH

https://api.withverifa.com/api/v1/consortiums/:consortium_id/matches/:match_id

PATCH

/api/v1/consortiums/:consortium_id/matches/:match_id

$ curl -X PATCH https://api.withverifa.com/api/v1/consortiums/consortium_id/matches/match_id \
>      -H "X-API-Key: <apiKey>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "status": "new"
> }'

1 {
2   "id": "cm_abc123",
3   "consortium_id": "string",
4   "match_type": "face",
5   "status": "new",
6   "created_at": "2024-01-15T09:30:00Z",
7   "face_similarity_score": 1.1,
8   "name_mismatch": true,
9   "dob_mismatch": true,
10   "document_type_mismatch": true,
11   "document_number_match": true,
12   "email_match": true,
13   "phone_match": true,
14   "device_match": true,
15   "days_between": 1,
16   "ghost_student_score": 1,
17   "ghost_student_tier": "pass",
18   "primary_session_id": "string",
19   "primary_org_id": "string",
20   "matched_session_id": "string",
21   "matched_org_id": "string",
22   "primary_org_name": "string",
23   "matched_org_name": "string",
24   "investigated_by": "string",
25   "investigated_at": "2024-01-15T09:30:00Z",
26   "resolution_notes": "string",
27   "updated_at": "2024-01-15T09:30:00Z"
28 }

Update the investigation status of a consortium match. Terminal statuses (confirmed_fraud, false_positive, resolved) trigger a consortium.investigation_updated webhook to both organizations involved. The peer’s payload is gated by the acting organization’s sharing policy.

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

Update the investigation status of a consortium match. Terminal statuses (`confirmed_fraud`, `false_positive`, `resolved`) trigger a `consortium.investigation_updated` webhook to both organizations involved. The peer's payload is gated by the acting organization's sharing policy. Setting status to `confirmed_fraud` automatically triggers fraud ring detection via BFS traversal of connected sessions.

Authentication

X-API-Keystring

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

Path parameters

consortium_idstringRequired

match_idstringRequired

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

statusenum

created_atdatetime

face_similarity_scoredouble or nullOptional

Cosine similarity between face embeddings (0–1).

name_mismatchbooleanOptional

True if the names on the two sessions differ.

dob_mismatchbooleanOptional

True if the dates of birth differ.

document_type_mismatchbooleanOptional

document_number_matchbooleanOptional

True if the same document number appears at both orgs.

email_matchbooleanOptional

phone_matchbooleanOptional

device_matchbooleanOptional

days_betweeninteger or nullOptional

Days between the two sessions' creation dates.

ghost_student_scoreinteger or nullOptional

Composite fraud risk score (0–100).

ghost_student_tierenumOptional

Risk tier derived from ghost_student_score.

primary_session_idstring or nullOptional

Present when sharing_level is “match_details” or higher.

primary_org_idstring or nullOptional

matched_session_idstring or nullOptional

matched_org_idstring or nullOptional

primary_org_namestring or nullOptional

matched_org_namestring or nullOptional

investigated_bystring or nullOptional

investigated_atdatetime or nullOptional

resolution_notesstring or nullOptional

Present when sharing_level is “full_investigation”.

updated_atdatetimeOptional

Errors

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

Authentication

Path parameters

Headers

Request

Response

Errors