Welcome to the BlueNotary API! This guide walks you through authentication, creating your first notarization session, handling events via webhooks, and retrieving signed documents. By the end, you’ll be able to run a full end-to-end notarization workflow.

1. Authentication

All requests require your API key. Include it in the request headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

If your API key is missing or invalid, the API will return a 401 Unauthorized error:

Internal Server Error

2.Base URL & Version

All v2 API requests use the following base URL: https://app.bluenotary.us/api/integrationsv2/

Example: https://app.bluenotary.us/api/integrationsv2/sessions/

3. Create Your First Notarization Session

The Create Session endpoint initializes a notarization session.

Required Fields

Field	Type	Description
'notarization_id'	string	Your unique ID to track the session (max 255 chars).
'all_signers'	array of objets	Signer info (see below).
'all_signers[0].first_name'	string	First name of the signer
'all_signers[0].last_name'	string	Last name of the signer (1–50 chars)
'all_signers[0].email'	string	Valid email address of the signer

Note: Documents are not required to be uploaded and can be uploaded subsequently using Add Document API.

4. Working with Documents

You can upload documents by converting them as Base64 string and passing it along in the API.

You can convert a file to Base64 using an online tool or using local libraries, for example:

fs.readFileSync("file.pdf").toString("base64");

import base64
with open("file.pdf", "rb") as f:
    base64.b64encode(f.read()).decode("utf-8")

Example Request

curl --request POST \
  --url https://app.bluenotary.us/api/integrationsv2/sessions \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
	"notarization_id": "1231231234",
	"signing_type": "gnw",
	"notarization_timing_type": "notarize_now",
  "all_signers": [
    {
      "email": "[email protected]",
      "first_name": "Avi",
      "last_name": "Shah"
    }
  ]
}'

Example Success Response

200 OK

{
	"response": "Pass",
	"response_message": "Session created successfully",
	"notarization_id": "1231231234",
	"bn_session_id": "68caac9b35f2077f014a28d8",
	"signing_urls": [
		{
			"signer_index": 0,
			"bn_signing_url": "/sign-in?type=customer&[email protected]&password=$2a$10$j/go..5pTex7CON6hqHjt.zvO.5NgYqRo5HnnZSiJzhIWYNGHqIOO&loginViaEmail=true&sessionid=68caac9b35f2077f014a28d8&routetype=pdfEdit&autosubmit=true",
			"full_signing_url": "https://app.bluenotary.us/sign-in?type=customer&[email protected]&password=$2a$10$j/go..5pTex7CON6hqHjt.zvO.5NgYqRo5HnnZSiJzhIWYNGHqIOO&loginViaEmail=true&sessionid=68caac9b35f2077f014a28d8&routetype=pdfEdit&autosubmit=true"
		}
	],
	"witnessess_signing_urls": []
}

Example Error Response

403 Forbidden

{
	"response": "Fail",
	"response_message": "signing_type fields are missing in request",
	"notarization_id": "",
	"bn_session_id": "",
	"bn_signing_url": ""
}

5. Consume Session Events (Webhooks)

You can keep an ongoing status of what's happening in the session by consuming the session update events. To configure, reach out to your account manager or support team to register.

For example, the join_session will tell you that a participant has joined the session, session_started will tell you when the session is started, session_completed will tell you when the session is completed.

You can configure

6. Retrieve Signed Documents

To download signed documents via URL, use Get Signed Document API on completed sessions:

GET https://app.bluenotary.us/api/integrationsv2/sessions/{bn_session_id}/documents

Returns metadata and download URLs.

7. Status Codes at a Glance

Code	Meaning
201	Created – Session successfully created
400	Bad Request – Validation failed
401	Unauthorized – Invalid API key
404	Not Found – Invalid session ID
500	Server Error – Try again later

Getting Started with the BlueNotary API