Event catalog
Understand the event families, their business meaning, and the difference between progress and final completion.
Session lifecycle
Use lifecycle events to follow the session, while keeping the session status field and event name as separate vocabularies.
| Event | Meaning / handling |
|---|---|
| session_started | The session has started. |
| session_completed_clicked | Completion was requested; document processing begins. |
| session_completed | Final completion; handle the selected artifact delivery. |
| session_terminated | Session terminated or cancelled. |
| session_expired | Session expired. |
| session_rescheduled | Meeting details changed; inspect the new timing fields. |
Assignment and participants
These events can recur. Preserve legitimate repeated activity and avoid collapsing every event with the same session and type.
| Event | Meaning |
|---|---|
| open_call_accepted | A notary accepts the open call. |
| join_session | A participant joins. |
| leave_session | A participant leaves. |
| additional_signer_invited | An additional signer is invited through the supported session flow. |
Identity and KBA
Subscribe to identity events when your product needs that progress. A completed identity step is not a completed notarization.
| Event | Stage |
|---|---|
| photo_id_passed / photo_id_failed | Photo identity result. |
| biometrics_passed | Biometric step passed. |
| kba_started / kba_answered | First KBA set progress. |
| kba_first_set_failed | First set failed. |
| kba_second_set_started / kba_answered_second | Second KBA set progress. |
| kba_second_set_failed | Second set failed. |
| kba_succeeded / kba_failed | KBA outcome. |
| kba_session_expired / kba_session_second_expired | The relevant KBA attempt expired. |
| personal_details_filled | Personal details were completed in the applicable vendor flow. |
eSign and certificates
Treat individual signing actions and stages separately from session completion.
| Event | Document array / use |
|---|---|
| esign_action_completed | Per-action completion; signed_files can carry artifacts. |
| stage_completed | A stage completed in a staged eSign workflow. |
| signature_certificate | Certificate artifact event; session_reports can carry outputs. |
| session_completed | Final session documents appear in final_output_files when applicable. |
Account events
new_business_account_added is an account event. Do not assume every account event has a non-null session identifier. Route account and session handlers according to the event family.
Correlate and deduplicate
Persist the correlation fields your system needs and distinguish an event’s occurrence from a delivery attempt.
| Field | Purpose |
|---|---|
| notarization_id | Your application correlation reference; can be null. |
| bn_session_id | BlueNotary session identifier; can be null where not applicable. |
| session_reference_number | Additional human-facing reference when present. |
| event_timestamp | When the event occurred. |
| delivery_id | Managed delivery identity stable across retries. |
| req_id | Managed attempt identity for diagnostics. |
| stage_position | Stage context for applicable staged eSign events. |
Keep subscriptions intentional
Choose the events that drive your application. Selecting all events can include future additions, so receivers must tolerate unknown types and optional fields. Test sample payloads for the document delivery mode and managed/legacy setup your account uses.