Cancel a session
Cancel unfinished work and optionally notify participants.
Overview
Cancel an active workflow, stop associated open-call and preparation work, and emit a termination event. The session remains available to Get Session. Cancellation is distinct from deleting a record or issuing a refund.
Use an owned session that has not completed or already been cancelled. Decide who should communicate cancellation to participants.
- Read current state
Confirm the session can still be cancelled.
- Choose notification behavior
Send a boolean and a customer-safe reason if needed.
- Reconcile cancellation
Persist the outcome and process the termination event.
Parameters
| Field | Requirement | Description |
|---|---|---|
bn_session_idstring · path | Required | The BlueNotary session ID. |
reasonstring | Optional | The reason for cancellation. Use concise customer-safe text and avoid sensitive information. |
notify_participantsboolean | Optional | Defaults to true. Send the JSON boolean false to disable cancellation notifications; the string "false" is not equivalent. |
Request example
Use a server-side API key. Replace example IDs and values before using this request in an approved test environment.
curl --request PUT \
--url 'https://app.bluenotary.us/api/integrationsv2/sessions/YOUR_SESSION_ID/cancel' \
--header "Authorization: Bearer $BLUENOTARY_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"reason": "The customer requested a different appointment.",
"notify_participants": true
}'Response
200 · Example success Illustrative values in the current response shape.
{
"success": true,
"session_id": "69a100000000000000001042",
"notarization_id": "order-1042",
"status": "cancelled"
}- The success body uses
session_id, while creation usesbn_session_id. - The termination webhook is separate from participant email notifications.
- Cancellation does not constitute a documented refund guarantee.
- A timeout can occur after state changed. Read the session before attempting the mutation again.
Errors & recovery
| Status | What happened | What to do |
|---|---|---|
| 400 | session_already_completed | Do not cancel a completed session; handle any financial question through the applicable billing process. |
| 400 | session_already_cancelled | Reconcile your application to the cancelled state. |
| 409 | session_state_conflict | Read the latest state before deciding whether to repeat the action. |
| 403 | Session Not Found | Check the session ID and account ownership. |
Explore the response
Response simulator
LOCAL EXAMPLEExplore the example response without an API key. This does not send requests or validate your account configuration.