Case - Event Callbacks

Event callbacks provide real-time updates as the verification progresses through different stages.

Endpoint Configuration: events_callback_url

Available Events

Event Type	Trigger	Payload Content
`VERIFICATION_SESSION_STARTED`	User begins the verification session	`verification_session_id`, `client_reference_id`, `client_reference_data`
`VERIFICATION_REQUEST_SUBMITTED`	User completes data entry and submits	`verification_session_id`, `client_reference_id`, `client_reference_data`
`VERIFICATION_SESSION_COMPLETION`	Verification workflow finishes	Full `UserVerificationResultPayload`
`CASE_STATUS_UPDATE`	Reviewer or API updates the case decision	`verification_session_id`, `verification_result`, `author`, `reason`
`AML_MONITORING_UPDATE`	Ongoing AML monitoring detects a change	`verification_session_id`, `aml_monitoring_update` object
`SECTION_INFO_UPDATE`	Analyst edits verification data	`verification_session_id`, `data` (section details, previous/current values)
`COMMENT`	Comment is added to the case	`verification_session_id`, `comment`, `author`, `created_at

Event Payload Structure

Common Fields (Present in all events):

{
  "event_type": "VERIFICATION_SESSION_STARTED",
  "verification_session_id": "vs_abc123",
  "client_reference_id": "your_user_id_123",
  "client_reference_data": {
    "custom_field": "custom_value"
  }
}

Event 1: VERIFICATION_SESSION_STARTED

Description: Triggered when the hosted flow or SDK hands control back and the user begins the verification session.

Use Cases:

Track session initiation in your analytics
Update user interface to show "verification in progress"
Log session start time for audit purposes

Payload:

{
  "event_type": "VERIFICATION_SESSION_STARTED",
  "verification_session_id": "vs_abc123",
  "client_reference_id": "user_12345",
  "client_reference_data": {
    "user_tier": "premium",
    "referral_source": "mobile_app"
  }
}

Event 2: VERIFICATION_REQUEST_SUBMITTED

Description: Triggered when the user completes data entry and the workflow moves into processing.

Use Cases:

Notify user that their verification is being processed
Update status in your database from "collecting" to "processing"
Trigger background tasks that depend on submission

Payload:

{
  "event_type": "VERIFICATION_REQUEST_SUBMITTED",
  "verification_session_id": "vs_abc123",
  "client_reference_id": "user_12345",
  "client_reference_data": {
    "user_tier": "premium"
  }
}

Event 3: VERIFICATION_SESSION_COMPLETION

Description: Verification workflow finishes with a terminal status (approved, declined, manual review, or failed).

Use Cases:

Update verification status in your system
Trigger downstream workflows based on result
Send notifications to users
Update access permissions

Payload: Contains the full UserVerificationResultPayload (see Decision Callback for structure).

{
  "event_type": "VERIFICATION_SESSION_COMPLETION",
  "verification_session_id": "vs_abc123",
  "template_id": "tmpl_kyc_basic",
  "client_reference_id": "user_12345",
  "aiprise_summary": {
    "decision": "APPROVED",
    "status": "COMPLETED",
    "warning_codes": [],
    "reasons": [],
    "notes": ""
  },
  "status": "COMPLETED",
  "created_at": 1702345678000,
  "user_input": { /* user data */ },
  "id_info": { /* ID verification results */ },
  "face_match_info": { /* face comparison results */ },
  "aml_info": { /* AML screening results */ }
  // ... additional fields
}

Event 4: CASE_STATUS_UPDATE

Description: Reviewer or API client manually updates the case decision after initial completion.

Use Cases:

Handle manual review decisions
Update user status when reviewers override decisions
Trigger compliance workflows
Log decision changes for audit

Payload:

{
  "event_type": "CASE_STATUS_UPDATE",
  "verification_session_id": "vs_abc123",
  "client_reference_id": "user_12345",
  "verification_result": "DECLINED",
  "author": {
    "email_address": "[email protected]",
    "name": "Jane Reviewer"
  },
  "author_id": "[email protected]",
  "reason": "Document quality insufficient - requested resubmission"
}

Event 5: AML_MONITORING_UPDATE

Description: Ongoing AML monitoring detects a new match or status change for the user.

Use Cases:

React to sanctions list additions
Handle PEP status changes
Trigger compliance team notifications
Update risk profiles

Payload:

{
  "event_type": "AML_MONITORING_UPDATE",
  "verification_session_id": "vs_abc123",
  "client_reference_id": "user_12345",
  "aml_monitoring_update": {
    "monitoring_run_id": "mon_xyz789",
    "status": "MATCH_FOUND",
    "matches": [
      {
        "list_name": "OFAC SDN",
        "entity_name": "John Doe",
        "confidence": 0.92,
        "reference_url": "https://..."
      }
    ],
    "previous_status": "CLEAR"
  }
}

Event 6: SECTION_INFO_UPDATE

Description: Analyst edits a section (such as ID info, address, or personal details) in the dashboard or via API.

Use Cases:

Track manual corrections
Sync updated data to your database
Audit data changes
Re-validate affected workflows

Payload:

{
  "event_type": "SECTION_INFO_UPDATE",
  "verification_session_id": "vs_abc123",
  "client_reference_id": "user_12345",
  "data": {
    "section_name": "address",
    "updated_fields": {
      "street": {
        "previous": "123 Main St",
        "current": "123 Main Street"
      },
      "postal_code": {
        "previous": "12345",
        "current": "12345-6789"
      }
    },
    "updated_by": "[email protected]",
    "updated_at": 1702345678000
  }
}

Event 7: COMMENT

Description: Comment is posted on the case by a reviewer, Compliance Copilot, or automation.

Use Cases:

Display reviewer notes in your admin interface
Track case history
Trigger notifications for important comments
Capture compliance annotations

Payload:

{
  "event_type": "COMMENT",
  "verification_session_id": "vs_abc123",
  "client_reference_id": "user_12345",
  "comment": "ID document appears to be a scanned copy, not original capture. Requesting resubmission.",
  "author": {
    "email_address": "[email protected]",
    "name": "Jane Reviewer"
  },
  "author_id": "[email protected]",
  "created_at": 1702345678000
}