Create RON Sessions

Remote Online Notarization (RON) sessions connect signers with a notary over live video. This guide covers everything you need to create a RON session via the BlueNotary API.

Other signing types: For eSign-only sessions, see Create an eSign Session. For In-Person Electronic Notarization (IPEN), see Create an IPEN Session.

Base URL

POST https://{your-domain}/api/integrationsv2/sessions

Replace {your-domain} with app.bluenotary.us or your custom white-label domain if applicable.

Authentication

All requests require a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Your API key is available in your BlueNotary Business Admin account under Settings → API.

Request Parameters

Top-Level Fields

Field	Type	Required	Description
`signing_type`	string	Yes	Must be `"ron"` for Remote Online Notarization.
`notarization_id`	string	No	Your own reference ID for this session. Returned as a query parameter on the completion redirect page. Can be any alphanumeric string.
`all_signers`	array	Yes	List of signers. See Signers Object below.
`session_type`	string	No	`"closing"` for mortgage/loan closings, `"gnw"` for general notarization. Defaults to `"closing"`.
`notarization_timing_type`	string	Yes	`"notarize_now"` for on-demand notary assignment, or `"notarize_later"` to schedule a specific time.
`session_timing`	string	Conditional	Required when `notarization_timing_type` is `"notarize_later"`. ISO 8601 datetime string, e.g. `"2024-09-15T10:00:00-05:00"`.
`session_notary_email`	string	Conditional	Required when assigning a specific notary from your team. Must be a notary user on your Business Admin account. If omitted, BlueNotary assigns an on-demand notary from the network.
`notarization_types`	string	No	The notarial act(s) required. Comma-separated for multiple. Common values: `"Acknowledgement"`, `"Jurat"`, `"Oath"`, `"Copy Certification"`. Defaults to `"Acknowledgement"`.
`witnesses`	object	No	Configure witnesses for the session. See Witnesses Object.
`session_documents`	array	No	Documents to be notarized, uploaded as base64. See Documents Object. Required if `document_templates` is not provided.
`document_templates`	array	No	List of template IDs from your BlueNotary account to use instead of uploading documents. Required if `session_documents` is not provided.
`final_documents_delivery_mode`	string	No	`"immediately"` delivers signed documents to signers upon session completion (default). `"notary_manual"` holds delivery until the notary manually releases them.
`send_invite_after_pretagging`	string	No	When `true`, invitation emails are held until the session notary, pretagger, or admin marks the document as pretagged. Useful when using templates that require annotation review before signers are notified. Defaults to `false`.
`loan_details`	object	No	Required for eClosing sessions (`session_type: "closing"`). See eClosing Scenario.
`session_configurations`	object	No	Session-level overrides. See Session Configurations.

Signers Object

Each object in all_signers represents one signer.

Field	Type	Required	Description
`email`	string	Yes	Signer's email address.
`first_name`	string	Yes	Signer's first name.
`last_name`	string	Yes	Signer's last name.
`middle_name`	string	No	Signer's middle name.
`suffix`	string	No	Name suffix. Accepted values: `J`, `Jr`, `JR`, `S`, `Sr`, `SR`, `I`, `II`, `III`, `IV`, `V`, `VI`, `VII`, `VIII`, `IX`, `2`–`9`.
`address`	string	No	Street address.
`city`	string	No	City.
`state`	string	No	State abbreviation, e.g. `"CA"`.
`zip`	string	No	ZIP code.
`contact_method`	string	No	Contact method, e.g. `"Mobile"`.
`contact_details`	string	No	Contact value, e.g. phone number.
`authentication_type`	string	No	Identity verification method for the signer when entering the session. `"kba"` (Knowledge-Based Authentication), `"biometrics"` (ID scan + selfie), or `"skip"` (no verification).
`is_shared_device_owner`	boolean	No	Set to `true` to designate this signer as the host in Same Device Signing mode. Only one signer can be the host. If not set, the primary signer (first in the array) is the host by default for RON sessions.

Witnesses Object

Field	Type	Description
`number_of_bluenotary_witnesses`	integer	Number of witnesses to source from the BlueNotary notary network. Defaults to `0`.
`bluenotary_witness_id_auth_required`	boolean	Set to `true` if BlueNotary-sourced witnesses must complete ID authentication. Defaults to `false`.
`invited_witness_details`	array	Provide your own witnesses. Each object requires `email` and optionally `firstname`, `lastname`, `phoneNumber`, `witnessAdressLine1`, `witnessAddressState`, `isPhysicallyPresent`, and `need_id_auth`.

Documents Object

Each object in session_documents represents one document.

Field	Type	Required	Description
`name`	string	Yes	File name including extension, e.g. `"deed.pdf"`.
`base64Doc`	string	Yes	Base64-encoded document content. Supported formats: PDF, DOCX, TXT, JPG, PNG. Maximum file size: 10MB per document.
`applyTemplate`	string	No	Template ID to use for auto-tagging this document. The uploaded PDF must match the template's original PDF.
`annotations`	array	No	Pre-placed annotation fields. Each annotation requires `fieldType`, `pageNum`, `x`, `y`, `width`, `height`, and `role`. See the Annotations reference for full field definitions.
`notary_can_edit_documents`	boolean	No	Allow the session notary to add new annotations to this document. Defaults to `false`.

Session Configurations

Field	Type	Description
`auto_expire_session_on`	string	ISO 8601 datetime after which the session is automatically expired.
`notary_can_edit_documents`	boolean	Allow the notary to add annotations across all session documents. Defaults to `false`. Overrides the per-document setting.
`same_device_signing_mode`	string	Set to `"all"` to enable Same Device Signing. In this mode, all signers share one physical device. The host signer joins first and manages access for other signers. See Same Device Signing scenario.
`delay_threshold`	object	Controls the modal shown to participants if the notary is late to join. Accepts `title`, `message`, and up to 2 `actions` (link buttons). Overrides your account-level defaults.

Response

A successful 200 response returns the following fields:

Field	Description
`response`	`"Pass"` on success.
`response_message`	Human-readable status, e.g. `"Session created successfully"`.
`notarization_id`	The `notarization_id` you provided in the request, echoed back.
`bn_session_id`	BlueNotary's unique ID for this session. Store this — you'll need it for status lookups and webhooks.
`bn_signing_url`	Relative signing URL for the primary signer (first in `all_signers`).
`full_signing_url`	Absolute signing URL for the primary signer. Redirect the signer to this URL or embed it in your application to launch their session.
`additional_signers_signing_urls`	Array of `{bn_signing_url, full_signing_url}` objects for each additional signer, in the same order as `all_signers[1...]`. Distribute each URL only to the corresponding signer — each URL is personalized and pre-authenticated.
`witnessess_signing_urls`	Array of signing URLs for any invited witnesses, in the same order as `witnesses.invited_witness_details`.

Security note: Each full_signing_url contains a pre-authenticated token for that specific signer. Do not share one signer's URL with another participant.

Scenarios

Scenario 1: On-Demand Notary (Notarize Now)

The simplest RON session. BlueNotary automatically assigns an available notary from its network. The signer can join immediately after receiving their invitation.

Omit session_notary_email — leaving it blank triggers on-demand assignment.

curl

curl --location 'https://app.bluenotary.us/api/integrationsv2/sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "signing_type": "ron",
  "notarization_id": "order-001",
  "notarization_timing_type": "notarize_now",
  "notarization_types": "Acknowledgement",
  "all_signers": [
    {
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Doe",
      "authentication_type": "kba"
    }
  ],
  "session_documents": [
    {
      "name": "power-of-attorney.pdf",
      "base64Doc": "YOUR_BASE64_ENCODED_PDF"
    }
  ]
}'

JavaScript (fetch)

const response = await fetch('https://app.bluenotary.us/api/integrationsv2/sessions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    signing_type: 'ron',
    notarization_id: 'order-001',
    notarization_timing_type: 'notarize_now',
    notarization_types: 'Acknowledgement',
    all_signers: [
      {
        email: '[email protected]',
        first_name: 'Jane',
        last_name: 'Doe',
        authentication_type: 'kba'
      }
    ],
    session_documents: [
      {
        name: 'power-of-attorney.pdf',
        base64Doc: 'YOUR_BASE64_ENCODED_PDF'
      }
    ]
  })
});

const data = await response.json();
console.log(data.full_signing_url); // Redirect the signer here

Node.js

const request = require('request');

request({
  method: 'POST',
  url: 'https://app.bluenotary.us/api/integrationsv2/sessions',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  json: {
    signing_type: 'ron',
    notarization_id: 'order-001',
    notarization_timing_type: 'notarize_now',
    notarization_types: 'Acknowledgement',
    all_signers: [
      {
        email: '[email protected]',
        first_name: 'Jane',
        last_name: 'Doe',
        authentication_type: 'kba'
      }
    ],
    session_documents: [
      {
        name: 'power-of-attorney.pdf',
        base64Doc: 'YOUR_BASE64_ENCODED_PDF'
      }
    ]
  }
}, (error, response, body) => {
  if (error) throw new Error(error);
  console.log(body.full_signing_url); // Redirect the signer here
});

Sample Response

{
  "response": "Pass",
  "response_message": "Session created successfully",
  "notarization_id": "order-001",
  "bn_session_id": "67af8e4d1dfa453d2a05b24e",
  "bn_signing_url": "/sign-in?type=customer&...",
  "full_signing_url": "https://app.bluenotary.us/sign-in?type=customer&...",
  "additional_signers_signing_urls": [],
  "witnessess_signing_urls": []
}

Scenario 2: Schedule for Later

Use notarize_later when you want the session to occur at a specific date and time. The signer receives an invitation with the scheduled time, and the notary is assigned closer to the session start.

curl

curl --location 'https://app.bluenotary.us/api/integrationsv2/sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "signing_type": "ron",
  "notarization_id": "order-002",
  "notarization_timing_type": "notarize_later",
  "session_timing": "2024-09-15T10:00:00-05:00",
  "notarization_types": "Acknowledgement",
  "all_signers": [
    {
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Doe",
      "authentication_type": "kba"
    }
  ],
  "session_documents": [
    {
      "name": "deed.pdf",
      "base64Doc": "YOUR_BASE64_ENCODED_PDF"
    }
  ]
}'

JavaScript (fetch)

const response = await fetch('https://app.bluenotary.us/api/integrationsv2/sessions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    signing_type: 'ron',
    notarization_id: 'order-002',
    notarization_timing_type: 'notarize_later',
    session_timing: '2024-09-15T10:00:00-05:00',
    notarization_types: 'Acknowledgement',
    all_signers: [
      {
        email: '[email protected]',
        first_name: 'Jane',
        last_name: 'Doe',
        authentication_type: 'kba'
      }
    ],
    session_documents: [
      {
        name: 'deed.pdf',
        base64Doc: 'YOUR_BASE64_ENCODED_PDF'
      }
    ]
  })
});

const data = await response.json();

Node.js

request({
  method: 'POST',
  url: 'https://app.bluenotary.us/api/integrationsv2/sessions',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  json: {
    signing_type: 'ron',
    notarization_id: 'order-002',
    notarization_timing_type: 'notarize_later',
    session_timing: '2024-09-15T10:00:00-05:00',
    notarization_types: 'Acknowledgement',
    all_signers: [
      {
        email: '[email protected]',
        first_name: 'Jane',
        last_name: 'Doe',
        authentication_type: 'kba'
      }
    ],
    session_documents: [
      {
        name: 'deed.pdf',
        base64Doc: 'YOUR_BASE64_ENCODED_PDF'
      }
    ]
  }
}, (error, response, body) => {
  console.log(body);
});

Timezone note: Always include the UTC offset in session_timing. 2024-09-15T10:00:00-05:00 means 10:00 AM Central time. Omitting the offset may cause the session to be scheduled in the wrong timezone.

Scenario 3: Team Notary (Assign Your Own Notary)

Use session_notary_email to assign a specific notary from your Business Admin account. The notary must already exist as a notary user under your account. This is the recommended approach when you have a dedicated notary workforce.

curl

curl --location 'https://app.bluenotary.us/api/integrationsv2/sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "signing_type": "ron",
  "notarization_id": "order-003",
  "notarization_timing_type": "notarize_later",
  "session_timing": "2024-09-15T14:00:00-05:00",
  "session_notary_email": "[email protected]",
  "notarization_types": "Acknowledgement",
  "all_signers": [
    {
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Doe",
      "authentication_type": "kba"
    }
  ],
  "session_documents": [
    {
      "name": "affidavit.pdf",
      "base64Doc": "YOUR_BASE64_ENCODED_PDF"
    }
  ]
}'

JavaScript (fetch)

const response = await fetch('https://app.bluenotary.us/api/integrationsv2/sessions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    signing_type: 'ron',
    notarization_id: 'order-003',
    notarization_timing_type: 'notarize_later',
    session_timing: '2024-09-15T14:00:00-05:00',
    session_notary_email: '[email protected]',
    notarization_types: 'Acknowledgement',
    all_signers: [
      {
        email: '[email protected]',
        first_name: 'Jane',
        last_name: 'Doe',
        authentication_type: 'kba'
      }
    ],
    session_documents: [
      {
        name: 'affidavit.pdf',
        base64Doc: 'YOUR_BASE64_ENCODED_PDF'
      }
    ]
  })
});

Node.js

request({
  method: 'POST',
  url: 'https://app.bluenotary.us/api/integrationsv2/sessions',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  json: {
    signing_type: 'ron',
    notarization_id: 'order-003',
    notarization_timing_type: 'notarize_later',
    session_timing: '2024-09-15T14:00:00-05:00',
    session_notary_email: '[email protected]',
    notarization_types: 'Acknowledgement',
    all_signers: [
      {
        email: '[email protected]',
        first_name: 'Jane',
        last_name: 'Doe',
        authentication_type: 'kba'
      }
    ],
    session_documents: [
      {
        name: 'affidavit.pdf',
        base64Doc: 'YOUR_BASE64_ENCODED_PDF'
      }
    ]
  }
}, (error, response, body) => {
  console.log(body);
});

Prerequisites: The email in session_notary_email must belong to a notary user created under your Business Admin account. If the email is not found or is not credentialed as a notary, the request will fail.

Scenario 4: State-Specific Notary

By default, BlueNotary allows cross-state notarization and selects from the full notary network. Use state_specific_notary only when your transaction legally requires a notary commissioned in a particular state. Note that specifying a state significantly reduces the available notary pool and may increase wait times.

curl

curl --location 'https://app.bluenotary.us/api/integrationsv2/sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "signing_type": "ron",
  "notarization_id": "order-004",
  "notarization_timing_type": "notarize_now",
  "state_specific_notary": "Florida",
  "notarization_types": "Acknowledgement",
  "all_signers": [
    {
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Doe",
      "authentication_type": "kba"
    }
  ],
  "session_documents": [
    {
      "name": "contract.pdf",
      "base64Doc": "YOUR_BASE64_ENCODED_PDF"
    }
  ]
}'

JavaScript (fetch)

const response = await fetch('https://app.bluenotary.us/api/integrationsv2/sessions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    signing_type: 'ron',
    notarization_id: 'order-004',
    notarization_timing_type: 'notarize_now',
    state_specific_notary: 'Florida',
    notarization_types: 'Acknowledgement',
    all_signers: [
      {
        email: '[email protected]',
        first_name: 'Jane',
        last_name: 'Doe',
        authentication_type: 'kba'
      }
    ],
    session_documents: [
      {
        name: 'contract.pdf',
        base64Doc: 'YOUR_BASE64_ENCODED_PDF'
      }
    ]
  })
});

Node.js

request({
  method: 'POST',
  url: 'https://app.bluenotary.us/api/integrationsv2/sessions',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  json: {
    signing_type: 'ron',
    notarization_id: 'order-004',
    notarization_timing_type: 'notarize_now',
    state_specific_notary: 'Florida',
    notarization_types: 'Acknowledgement',
    all_signers: [
      {
        email: '[email protected]',
        first_name: 'Jane',
        last_name: 'Doe',
        authentication_type: 'kba'
      }
    ],
    session_documents: [
      {
        name: 'contract.pdf',
        base64Doc: 'YOUR_BASE64_ENCODED_PDF'
      }
    ]
  }
}, (error, response, body) => {
  console.log(body);
});

Scenario 5: Using a Template Instead of Uploading a Document

If you have pre-configured document templates in your BlueNotary account (with signature fields, notary seals, and other annotations already placed), you can reference them by ID instead of uploading a base64 document. This avoids re-uploading the same document repeatedly and ensures consistent annotation placement.

Find your template IDs in your Business Admin account under Templates.

Optionally set send_invite_after_pretagging: true if you want to review annotation placement before the signer receives their invitation.

curl

curl --location 'https://app.bluenotary.us/api/integrationsv2/sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "signing_type": "ron",
  "notarization_id": "order-005",
  "notarization_timing_type": "notarize_now",
  "notarization_types": "Acknowledgement",
  "all_signers": [
    {
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Doe",
      "authentication_type": "kba"
    }
  ],
  "document_templates": ["template_id_abc123"]
}'

JavaScript (fetch)

const response = await fetch('https://app.bluenotary.us/api/integrationsv2/sessions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    signing_type: 'ron',
    notarization_id: 'order-005',
    notarization_timing_type: 'notarize_now',
    notarization_types: 'Acknowledgement',
    all_signers: [
      {
        email: '[email protected]',
        first_name: 'Jane',
        last_name: 'Doe',
        authentication_type: 'kba'
      }
    ],
    document_templates: ['template_id_abc123']
  })
});

Node.js

request({
  method: 'POST',
  url: 'https://app.bluenotary.us/api/integrationsv2/sessions',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  json: {
    signing_type: 'ron',
    notarization_id: 'order-005',
    notarization_timing_type: 'notarize_now',
    notarization_types: 'Acknowledgement',
    all_signers: [
      {
        email: '[email protected]',
        first_name: 'Jane',
        last_name: 'Doe',
        authentication_type: 'kba'
      }
    ],
    document_templates: ['template_id_abc123']
  }
}, (error, response, body) => {
  console.log(body);
});

Template vs. applyTemplate: document_templates replaces the need to upload a document entirely. If you upload a document via session_documents and also provide applyTemplate on that document, BlueNotary will attempt to auto-tag the uploaded PDF using the matching template's annotations. Both approaches require the PDF to match the template's original file.

Scenario 6: Same Device Signing

Use Same Device Signing when multiple signers are physically present in the same location and sharing one device. The host signer joins first; the session then prompts each additional signer to complete their portion in sequence on the same device.

For RON sessions, the primary signer (first in all_signers) is the default host. Set is_shared_device_owner: true on a specific signer to override this.

curl

curl --location 'https://app.bluenotary.us/api/integrationsv2/sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "signing_type": "ron",
  "notarization_id": "order-006",
  "notarization_timing_type": "notarize_now",
  "notarization_types": "Acknowledgement",
  "session_configurations": {
    "same_device_signing_mode": "all"
  },
  "all_signers": [
    {
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Doe",
      "authentication_type": "kba",
      "is_shared_device_owner": true
    },
    {
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "authentication_type": "kba"
    }
  ],
  "session_documents": [
    {
      "name": "joint-deed.pdf",
      "base64Doc": "YOUR_BASE64_ENCODED_PDF"
    }
  ]
}'

JavaScript (fetch)

const response = await fetch('https://app.bluenotary.us/api/integrationsv2/sessions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    signing_type: 'ron',
    notarization_id: 'order-006',
    notarization_timing_type: 'notarize_now',
    notarization_types: 'Acknowledgement',
    session_configurations: {
      same_device_signing_mode: 'all'
    },
    all_signers: [
      {
        email: '[email protected]',
        first_name: 'Jane',
        last_name: 'Doe',
        authentication_type: 'kba',
        is_shared_device_owner: true
      },
      {
        email: '[email protected]',
        first_name: 'John',
        last_name: 'Doe',
        authentication_type: 'kba'
      }
    ],
    session_documents: [
      {
        name: 'joint-deed.pdf',
        base64Doc: 'YOUR_BASE64_ENCODED_PDF'
      }
    ]
  })
});

Node.js

request({
  method: 'POST',
  url: 'https://app.bluenotary.us/api/integrationsv2/sessions',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  json: {
    signing_type: 'ron',
    notarization_id: 'order-006',
    notarization_timing_type: 'notarize_now',
    notarization_types: 'Acknowledgement',
    session_configurations: {
      same_device_signing_mode: 'all'
    },
    all_signers: [
      {
        email: '[email protected]',
        first_name: 'Jane',
        last_name: 'Doe',
        authentication_type: 'kba',
        is_shared_device_owner: true
      },
      {
        email: '[email protected]',
        first_name: 'John',
        last_name: 'Doe',
        authentication_type: 'kba'
      }
    ],
    session_documents: [
      {
        name: 'joint-deed.pdf',
        base64Doc: 'YOUR_BASE64_ENCODED_PDF'
      }
    ]
  }
}, (error, response, body) => {
  console.log(body);
});

Scenario 7: eClosing Session

An eClosing session is a RON session with mortgage or loan closing context attached. Use session_type: "closing" and populate the loan_details object with the relevant loan information. This enables loan-specific features in the session UI including loan number display and closing type labeling.

curl

curl --location 'https://app.bluenotary.us/api/integrationsv2/sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "signing_type": "ron",
  "session_type": "closing",
  "notarization_id": "loan-closing-007",
  "notarization_timing_type": "notarize_later",
  "session_timing": "2024-09-20T09:00:00-06:00",
  "notarization_types": "Acknowledgement",
  "loan_details": {
    "loan_number": "LN-20240920-001",
    "loan_session_type": "refinance",
    "other_details": {
      "property_address": "123 Main St",
      "property_city": "Austin",
      "property_state": "TX",
      "property_zip": "78701",
      "session_instructions": "Please review all pages carefully before signing."
    }
  },
  "all_signers": [
    {
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Doe",
      "authentication_type": "kba"
    }
  ],
  "session_documents": [
    {
      "name": "closing-package.pdf",
      "base64Doc": "YOUR_BASE64_ENCODED_PDF"
    }
  ]
}'

JavaScript (fetch)

const response = await fetch('https://app.bluenotary.us/api/integrationsv2/sessions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    signing_type: 'ron',
    session_type: 'closing',
    notarization_id: 'loan-closing-007',
    notarization_timing_type: 'notarize_later',
    session_timing: '2024-09-20T09:00:00-06:00',
    notarization_types: 'Acknowledgement',
    loan_details: {
      loan_number: 'LN-20240920-001',
      loan_session_type: 'refinance',
      other_details: {
        property_address: '123 Main St',
        property_city: 'Austin',
        property_state: 'TX',
        property_zip: '78701',
        session_instructions: 'Please review all pages carefully before signing.'
      }
    },
    all_signers: [
      {
        email: '[email protected]',
        first_name: 'Jane',
        last_name: 'Doe',
        authentication_type: 'kba'
      }
    ],
    session_documents: [
      {
        name: 'closing-package.pdf',
        base64Doc: 'YOUR_BASE64_ENCODED_PDF'
      }
    ]
  })
});

Node.js

request({
  method: 'POST',
  url: 'https://app.bluenotary.us/api/integrationsv2/sessions',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  json: {
    signing_type: 'ron',
    session_type: 'closing',
    notarization_id: 'loan-closing-007',
    notarization_timing_type: 'notarize_later',
    session_timing: '2024-09-20T09:00:00-06:00',
    notarization_types: 'Acknowledgement',
    loan_details: {
      loan_number: 'LN-20240920-001',
      loan_session_type: 'refinance',
      other_details: {
        property_address: '123 Main St',
        property_city: 'Austin',
        property_state: 'TX',
        property_zip: '78701',
        session_instructions: 'Please review all pages carefully before signing.'
      }
    },
    all_signers: [
      {
        email: '[email protected]',
        first_name: 'Jane',
        last_name: 'Doe',
        authentication_type: 'kba'
      }
    ],
    session_documents: [
      {
        name: 'closing-package.pdf',
        base64Doc: 'YOUR_BASE64_ENCODED_PDF'
      }
    ]
  }
}, (error, response, body) => {
  console.log(body);
});

loan_session_type values

Value	Description
`HELOC`	Home Equity Line of Credit
`refinance`	Refinance
`seller`	Seller closing
`cash`	Cash purchase
`borrower`	Borrower-side closing
`other`	Other — provide detail in `other_loan_session_type`

Scenario 8: Session with Witnesses

Some states require one or more witnesses in addition to the notary. BlueNotary supports two approaches: sourcing witnesses from the BlueNotary notary network, or inviting your own. You can combine both in the same session.

curl (BlueNotary witnesses)

curl --location 'https://app.bluenotary.us/api/integrationsv2/sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "signing_type": "ron",
  "notarization_id": "order-008a",
  "notarization_timing_type": "notarize_now",
  "notarization_types": "Acknowledgement",
  "witnesses": {
    "number_of_bluenotary_witnesses": 2,
    "bluenotary_witness_id_auth_required": false
  },
  "all_signers": [
    {
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Doe",
      "authentication_type": "kba"
    }
  ],
  "session_documents": [
    {
      "name": "will.pdf",
      "base64Doc": "YOUR_BASE64_ENCODED_PDF"
    }
  ]
}'

curl (Invited witnesses)

curl --location 'https://app.bluenotary.us/api/integrationsv2/sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "signing_type": "ron",
  "notarization_id": "order-008b",
  "notarization_timing_type": "notarize_now",
  "notarization_types": "Acknowledgement",
  "witnesses": {
    "invited_witness_details": [
      {
        "email": "[email protected]",
        "firstname": "Alice",
        "lastname": "Smith",
        "isPhysicallyPresent": false,
        "need_id_auth": false
      }
    ]
  },
  "all_signers": [
    {
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Doe",
      "authentication_type": "kba"
    }
  ],
  "session_documents": [
    {
      "name": "will.pdf",
      "base64Doc": "YOUR_BASE64_ENCODED_PDF"
    }
  ]
}'

The response will include signing URLs for invited witnesses in witnessess_signing_urls, in the same order as witnesses.invited_witness_details. BlueNotary-sourced witnesses are assigned and notified by the platform — no URLs are returned for them.

Error Handling

A failed request returns HTTP 403 with the following shape:

{
  "response": "Fail",
  "response_message": "...",
  "notarization_id": "",
  "bn_session_id": "",
  "bn_signing_url": ""
}

Common errors and how to resolve them:

`response_message`	Cause	Resolution
`notarization_timing_type fields are missing in request`	`notarization_timing_type` was not provided.	Add `"notarization_timing_type": "notarize_now"` or `"notarize_later"` to your request.
`session_timing is required when notarization_timing_type is notarize_later`	`notarize_later` was set but no `session_timing` was provided.	Add `session_timing` as an ISO 8601 datetime string.
`Invalid session_notary_email`	The notary email is not found under your Business Admin account, or the user is not credentialed as a notary.	Verify the email exists as a notary user in your account under Team → Notaries.
`Unauthorized` / `403` with no body	Missing or invalid API key.	Check that your `Authorization` header uses the format `Bearer YOUR_API_KEY` and that the key is active.
`all_signers must have at least one signer`	`all_signers` array was empty or missing.	Provide at least one signer with `email`, `first_name`, and `last_name`.
`session_documents or document_templates required`	Neither documents nor templates were provided.	Add either `session_documents` with a base64-encoded file, or `document_templates` with at least one template ID.
`Document exceeds maximum file size`	A base64-encoded document exceeds the 10MB limit.	Compress or split the document before encoding.

Other Signing Types

This guide covers RON sessions only.

eSign — For signature-only workflows without a notary, see Create an eSign Session.
IPEN — For In-Person Electronic Notarization where the notary and signer are physically co-located, see Create an IPEN Session.