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`
`CREATE_TICKET`	Ticket is created on the case	`verification_session_id`, ticket fields
`TICKET_STATUS_UPDATE`	Ticket status changes	`verification_session_id`, ticket fields, `previous_status`, `updated_by`
`TICKET_REVIEWER_UPDATE`	Ticket reviewer changes	`verification_session_id`, ticket fields, `data` (old and new reviewer)
`TICKET_REVIEW_QUEUE_UPDATE`	Ticket moves to another review queue	`verification_session_id`, ticket fields, `data` (old and new queue name)

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
}

Ticket Events

You get ticket events only if ticket management is enabled for your company. This page covers tickets on cases that are not linked to a user profile. Tickets on a profile go to the profile's events_callback_url.

All four ticket events carry the same ticket fields next to the common fields:

Field	Description
`ticket_id`	Unique ID of the ticket.
`target_id`	ID of the verification session the ticket belongs to.
`target_id_type`	Always `USER` for case tickets.
`ticket_status`	`OPEN` or `RESOLVED`.
`trigger`	The alert trigger that created the ticket: `CASE_GOES_TO_REVIEW`, `AML_MONITORING_UPDATE`, `ID_EXPIRES`, `DOCUMENT_EXPIRES`, `WEBSITE_MONITORING_UPDATE` or `PERIODIC_REVIEW`. No value when an alert did not create the ticket, for example when a reviewer created it by hand.
`review_queue`	The ticket's review queue, with `review_queue_id` and `name`. No value when the ticket is not in a queue.
`assignee`	The assigned reviewer, with `email`. No value when nobody is assigned.
`created_at`	When the ticket was created, as a Unix timestamp in milliseconds.
`resolved_at`	When the ticket was resolved, as a Unix timestamp in milliseconds. No value while the ticket is open.

A field with no value is left out of the payload, so treat a missing field as null.

Event 8: CREATE_TICKET

Description: Sent whenever a ticket is created on the case, for example by an alert on the template or by a reviewer in the dashboard.

Payload:

{
  "event_type": "CREATE_TICKET",
  "verification_session_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_reference_id": "user_12345",
  "callback_event_id": "0b6a1f52-8d3e-4c7a-9f21-3e5d7c9a1b40",
  "ticket_id": "8c1e2f4a-5b6d-4e7f-9a0b-1c2d3e4f5a6b",
  "target_id": "550e8400-e29b-41d4-a716-446655440000",
  "target_id_type": "USER",
  "ticket_status": "OPEN",
  "trigger": "CASE_GOES_TO_REVIEW",
  "review_queue": {
    "review_queue_id": "2b7d9e10-4c3a-4f8e-9d21-6a5b4c3d2e1f",
    "name": "High risk KYC"
  },
  "assignee": {
    "email": "[email protected]"
  },
  "created_at": 1757500000000
}

A new ticket can start with no queue and no reviewer. review_queue and assignee are then missing.

Event 9: TICKET_STATUS_UPDATE

Description: Sent when the ticket's status changes, for example when a reviewer resolves it in the dashboard. previous_status is the status before the change. updated_by holds the email of the dashboard user who made the change.

Payload:

{
  "event_type": "TICKET_STATUS_UPDATE",
  "verification_session_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_reference_id": "user_12345",
  "callback_event_id": "5e2c9d71-4a8b-4f36-b1e0-7d3f6a2c8e95",
  "ticket_id": "8c1e2f4a-5b6d-4e7f-9a0b-1c2d3e4f5a6b",
  "target_id": "550e8400-e29b-41d4-a716-446655440000",
  "target_id_type": "USER",
  "ticket_status": "RESOLVED",
  "trigger": "CASE_GOES_TO_REVIEW",
  "review_queue": {
    "review_queue_id": "2b7d9e10-4c3a-4f8e-9d21-6a5b4c3d2e1f",
    "name": "High risk KYC"
  },
  "assignee": {
    "email": "[email protected]"
  },
  "created_at": 1757500000000,
  "resolved_at": 1757600000000,
  "previous_status": "OPEN",
  "updated_by": {
    "email": "[email protected]"
  }
}

Event 10: TICKET_REVIEWER_UPDATE

Description: Sent when the ticket's reviewer changes. assignee is the new reviewer. data.old_reviewer and data.new_reviewer hold the reviewer before and after the change, each with name and email. When there was no reviewer on one side, both of its values are null.

Payload:

{
  "event_type": "TICKET_REVIEWER_UPDATE",
  "verification_session_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_reference_id": "user_12345",
  "callback_event_id": "9f4e7a23-1c6d-4b58-8e3f-2a7c5d9b0e16",
  "ticket_id": "8c1e2f4a-5b6d-4e7f-9a0b-1c2d3e4f5a6b",
  "target_id": "550e8400-e29b-41d4-a716-446655440000",
  "target_id_type": "USER",
  "ticket_status": "OPEN",
  "trigger": "CASE_GOES_TO_REVIEW",
  "review_queue": {
    "review_queue_id": "2b7d9e10-4c3a-4f8e-9d21-6a5b4c3d2e1f",
    "name": "High risk KYC"
  },
  "assignee": {
    "email": "[email protected]"
  },
  "created_at": 1757500000000,
  "data": {
    "old_reviewer": {
      "name": "Jane Doe",
      "email": "[email protected]"
    },
    "new_reviewer": {
      "name": "Bob Lee",
      "email": "[email protected]"
    }
  }
}

Event 11: TICKET_REVIEW_QUEUE_UPDATE

Description: Sent when a reviewer moves the ticket to another review queue in the dashboard. review_queue is the new queue. data.old_review_queue_name and data.new_review_queue_name hold the queue names before and after the move, or null when there was no queue.

Payload:

{
  "event_type": "TICKET_REVIEW_QUEUE_UPDATE",
  "verification_session_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_reference_id": "user_12345",
  "callback_event_id": "d3a8c6e1-7f2b-4e94-a5c0-6b1e9f3d7a28",
  "ticket_id": "8c1e2f4a-5b6d-4e7f-9a0b-1c2d3e4f5a6b",
  "target_id": "550e8400-e29b-41d4-a716-446655440000",
  "target_id_type": "USER",
  "ticket_status": "OPEN",
  "trigger": "CASE_GOES_TO_REVIEW",
  "review_queue": {
    "review_queue_id": "7e4f1a2b-9c8d-4e6f-a1b2-c3d4e5f60718",
    "name": "Escalations"
  },
  "assignee": {
    "email": "[email protected]"
  },
  "created_at": 1757500000000,
  "data": {
    "old_review_queue_name": "High risk KYC",
    "new_review_queue_name": "Escalations"
  }
}