Sessions API

Create a session

Start an online notarization, eSign, or in-person notarization workflow.

POST/sessions

Overview

Create the session, identify its participants, and receive personalized access links. Choose the signing product first, then add the fields for that workflow. A successful response confirms session creation; it does not confirm email delivery, notary acceptance, or final-document readiness.

Before you start

Use an API key for the intended account and approved test environment. Confirm notary routing, dispatch timing, and invitation settings for the account. For direct assignment, the notary must be linked to the owning business and eligible for the selected product.

Choose a recipe
Select product, notary source, timing, and invitation behavior.
Create and persist
Send the request and save the returned session ID and correlation reference.
Prepare and launch
Attach documents, confirm preparation, and distribute participant links.
Follow completion
Consume events and retrieve the final files when ready.

Parameters

Field	Requirement	Description
`signing_type` string · enum	Optional	Use `ron`, `esign`, or `ipen`. Explicitly send this field in integrations. Omission currently defaults to `ron`; `gnw` is not a signing type.
`notarization_id` string	Optional	Your order or transaction reference, echoed in responses and events. It is a correlation value, not an idempotency key.
`all_signers` array<object>	Required	Participants for the workflow. Each needs `first_name`, `last_name`, and `email`. eSign recipients also need an `action`.
`all_signers[].email` string · email	Required	The participant email. Send a separate record and distribute the correct personalized link to each participant.
`all_signers[].first_name / last_name` string	Required	Participant names. Invalid names containing disallowed special characters or links can be rejected.
`all_signers[].action` string · enum	Conditional	Required for eSign: `needs_to_sign`, `needs_to_view`, or `receives_a_copy`.
`session_type` string	Optional	For general notary work, explicitly use `gnw`. Confirm the supported recipe for loan and other categories. The legacy `closing` value is not a supported `session_type`.
`notarization_timing_type` string	Conditional	Required for RON/IPEN. Use `notarize_now` or `notarize_later`. Signer-selected timing needs a separately verified workflow.
`session_timing` string · date-time	Conditional	Required with `notarize_later`. Send an ISO 8601 timestamp with an explicit offset, such as `2030-01-15T10:00:00-05:00`.
`session_notary_email` string · email	Conditional	Assign a specific team notary. Required for IPEN. Omit for a pool-based open call; the account determines internal-team versus network routing.
`session_documents` array<object>	Optional	Documents containing `name` and `base64Doc`, with optional `annotations` and `applyTemplate`. Documents may be added later; prepare them before participant launch.
`document_templates` array<string>	Optional	Saved document template IDs. This copies saved documents; applying saved field positions to a new upload uses the document-level `applyTemplate` field.
`send_invite_after_pretagging` boolean	Optional	RON/IPEN preparation hold. `true` starts in pretagging and suppresses the initial invitation and automatic open-call branches. Document the release action.
`send_signer_emails` boolean	Optional	eSign only: override the account default for creation invitation emails. Global account suppression still applies. This is not established as a RON override.
`witnesses` object	Optional	Use `invited_witness_details` for your witnesses or `number_of_bluenotary_witnesses` for network witnesses. Confirm identity and routing requirements.
`session_configurations` object	Optional	RON supports `auto_expire_session_on`, `notary_can_edit_documents`, and `delay_threshold`. `same_device_signing_mode: "all"` is processed separately. Do not assume identical support in eSign.
`state_specific_notary` string	Optional	Restrict the notary pool to a named state when required. Account settings can disable this request-level option; a narrower pool can reduce availability.
`stages` array<object>	Conditional	eSign only. Each stage uses `party_ids` pointing to unique recipient `id` values. Every recipient appears exactly once. A stage requires a signing recipient; maximum 10 stages.

Request example

Use a server-side API key. Replace example IDs and values before using this request in an approved test environment.

curl --request POST \
  --url 'https://app.bluenotary.us/api/integrationsv2/sessions' \
  --header "Authorization: Bearer $BLUENOTARY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "notarization_id": "order-1042",
  "signing_type": "ron",
  "session_type": "gnw",
  "notarization_timing_type": "notarize_now",
  "all_signers": [
    {
      "first_name": "Sam",
      "last_name": "Signer",
      "email": "sam@example.com"
    }
  ]
}'

Response

200 · Example success Illustrative values in the current response shape.

{
  "response": "Pass",
  "response_message": "Session created successfully",
  "notarization_id": "order-1042",
  "bn_session_id": "69a100000000000000001042",
  "signing_urls": [
    {
      "signer_index": 0,
      "bn_signing_url": "/sign-in?REDACTED_SIGNING_TOKEN",
      "full_signing_url": "https://app.bluenotary.us/sign-in?REDACTED_SIGNING_TOKEN"
    }
  ],
  "witnessess_signing_urls": []
}

Store bn_session_id as the identifier for subsequent API calls. Preserve your own order reference alongside it.
Returned signing URLs are credentials. Keep them out of logs and deliver them only to the intended participant.
For ordinary RON, map signing_urls by signer_index. IPEN and shared-device flows have different link semantics.
A named notary URL is conditional on account configuration. Preserve the legacy response spelling witnessess_signing_urls.

Errors & recovery

Status	What happened	What to do
400	Invalid signing_type	Send ron, esign, or ipen. Put gnw in session_type.
400	Required timing or signer fields missing	Add all_signers and the fields required by the selected signing product.
400	Assigned notary is unavailable to this account	Check the exact email, business linkage, supported state, and approval status.
401	Missing, invalid, or expired API key	Use a valid Bearer key for the intended account.
500	Unexpected creation failure	Retain the returned request_id when present and reconcile before retrying; the outcome may be ambiguous.

Explore the response

Response simulator

LOCAL EXAMPLE

Explore the example response without an API key. This does not send requests or validate your account configuration.

Example request body

Product-specific options

Keep separate request models for RON, eSign, and IPEN. Sending every option in one payload makes dependencies difficult to understand.

RON/IPEN: notarization_types describes the act, defaulting to Acknowledgement. final_documents_delivery_mode supports immediately, notary_manual, and stripe_invoice_paid in this path; verify release behavior for the account.
eSign: esign_subject and esign_message customize invitations. Per-signer authentication, ordering, stages, and same-device workflows require their dedicated recipes.
RON: per-signer authentication_type can be kba, biometrics, or skip where the configured policy permits. Choose only an approved identity workflow.
For the same device RON flow, at most one signer may set is_shared_device_owner: true; the first signer is the default owner.

Keep building

Need help with your implementation?Visit the help center