Event Callbacks

Endpoint Configuration: events_callback_url

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

Available Events

Event Type	Trigger	Payload Content
`VERIFICATION_SESSION_STARTED`	Business begins the KYB session	`verification_session_id`, `client_reference_id`, `client_reference_data`
`VERIFICATION_REQUEST_SUBMITTED`	Business completes data entry	`verification_session_id`, `client_reference_id`, `client_reference_data`
`VERIFICATION_SESSION_COMPLETION`	KYB workflow finishes	Full `BusinessVerificationResultPayload`
`CASE_STATUS_UPDATE`	Reviewer updates the case decision	`verification_session_id`, `verification_result`, `author`, `reason`, optional officer/company references
`AML_MONITORING_UPDATE`	Ongoing AML monitoring detects a change	`verification_session_id`, `aml_monitoring_update` object
`SECTION_INFO_UPDATE`	Analyst edits business data	`verification_session_id`, `data` (section details, previous/current values)
`COMMENT`	Comment is added to the business 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": "bvs_abc123",
  "client_reference_id": "your_business_id_123",
  "client_reference_data": {
    "business_tier": "enterprise",
    "onboarding_source": "sales_referral"
  }
}

Event 1: VERIFICATION_SESSION_STARTED

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

Use Cases:

Track KYB session initiation in analytics
Update business onboarding status to "verification in progress"
Log session start time for compliance audit
Notify internal teams about new business onboarding

Payload:

{
  "event_type": "VERIFICATION_SESSION_STARTED",
  "verification_session_id": "bvs_abc123",
  "client_reference_id": "business_12345",
  "client_reference_data": {
    "business_tier": "enterprise",
    "industry": "fintech",
    "expected_volume": "high"
  }
}

Event 2: VERIFICATION_REQUEST_SUBMITTED

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

Use Cases:

Notify business that KYB is being processed
Update status from "collecting" to "processing"
Trigger compliance team notifications
Begin internal credit checks or due diligence

Payload:

{
  "event_type": "VERIFICATION_REQUEST_SUBMITTED",
  "verification_session_id": "bvs_abc123",
  "client_reference_id": "business_12345",
  "client_reference_data": {
    "business_tier": "enterprise"
  }
}

Event 3: VERIFICATION_SESSION_COMPLETION

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

Use Cases:

Update business verification status
Enable/disable business account features
Trigger contract generation for approved businesses
Send notifications to business representatives
Update risk assessment systems

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

{
  "event_type": "VERIFICATION_SESSION_COMPLETION",
  "verification_session_id": "bvs_abc123",
  "template_id": "tmpl_kyb_standard",
  "client_reference_id": "business_12345",
  "aiprise_summary": {
    "decision": "APPROVED",
    "status": "COMPLETED",
    "warning_codes": [],
    "reasons": [],
    "notes": "All business checks passed"
  },
  "status": "COMPLETED",
  "created_at": 1702345678000,
  "business_input": { /* business data */ },
  "business_info": { /* derived attributes */ },
  "registration_info": { /* registry lookups */ },
  "aml_info": { /* AML screening */ },
  "related_persons": [ /* officers/UBOs */ ],
  "related_companies": [ /* parent/subsidiaries */ ]
}

Event 4: CASE_STATUS_UPDATE

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

Use Cases:

Handle manual review decisions for complex business structures
Update business status when compliance overrides decisions
Trigger escalation workflows
Log decision changes for regulatory audit

Payload:

{
  "event_type": "CASE_STATUS_UPDATE",
  "verification_session_id": "bvs_abc123",
  "client_reference_id": "business_12345",
  "verification_result": "APPROVED",
  "author": {
    "email_address": "[email protected]",
    "name": "Senior Compliance Officer"
  },
  "author_id": "[email protected]",
  "reason": "Additional documentation verified - ownership structure confirmed",
  "person_reference_id": "person_ceo_456", // Optional - if related to specific officer
  "company_reference_id": null, // Optional - if related to parent/subsidiary
  "file_uuid": null // Optional - if related to specific document
}

Event 5: AML_MONITORING_UPDATE

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

Use Cases:

React to sanctions list additions for businesses
Handle beneficial owner sanctions
Trigger compliance team alerts
Update risk profiles and transaction limits
Suspend business operations if high-risk match

Payload:

{
  "event_type": "AML_MONITORING_UPDATE",
  "verification_session_id": "bvs_abc123",
  "client_reference_id": "business_12345",
  "aml_monitoring_update": {
    "monitoring_run_id": "mon_biz_xyz789",
    "status": "MATCH_FOUND",
    "matches": [
      {
        "list_name": "EU Consolidated Sanctions",
        "entity_name": "ABC Corporation Ltd",
        "confidence": 0.96,
        "reference_url": "https://sanctions.eu/..."
      }
    ],
    "previous_status": "CLEAR"
  }
}

Event 6: SECTION_INFO_UPDATE

Description: Analyst edits a section (business info, ownership structure, documents) in the dashboard or via API.

Use Cases:

Sync corrected business data to your systems
Track manual corrections to company information
Audit ownership structure changes
Re-trigger dependent workflows when critical data changes

Payload:

{
  "event_type": "SECTION_INFO_UPDATE",
  "verification_session_id": "bvs_abc123",
  "client_reference_id": "business_12345",
  "data": {
    "section_name": "business_address",
    "updated_fields": {
      "registered_address": {
        "previous": "123 Old Business Park",
        "current": "456 Corporate Plaza, Suite 100"
      },
      "trading_address": {
        "previous": "Same as registered",
        "current": "789 Main Street, Floor 3"
      }
    },
    "updated_by": "[email protected]",
    "updated_at": 1702345678000
  }
}

Event 7: COMMENT

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

Use Cases:

Display reviewer notes in admin interface
Track investigation history
Capture due diligence findings
Generate compliance audit trails

Payload:

{
  "event_type": "COMMENT",
  "verification_session_id": "bvs_abc123",
  "client_reference_id": "business_12345",
  "comment": "Ownership structure verified through Companies House. All UBOs identified and screened. Board resolution provided confirming authorized signatories.",
  "author": {
    "email_address": "[email protected]",
    "name": "Jane Compliance Analyst"
  },
  "author_id": "[email protected]",
  "created_at": 1702345678000
}