Documents API

Add documents

Attach PDF documents to an existing session.

POST/sessions/{bn_session_id}/documents

Overview

Upload one or more PDF documents as a JSON array containing locally encoded Base64 content. Optional annotations and template fields can prepare the files for signing. Check session and document state before adding to an existing workflow.

Before you start

The session belongs to this vendor and remains open for uploads. Prepare readable PDF content and encode it locally. Check whether the session’s merged document already has fields placed.

Prepare the PDF
Validate the document locally and encode its bytes.
Check session readiness
Confirm upload is allowed and merging has not locked the document set.
Upload and verify
Attach the file and inspect preparation before launching participants.

Parameters

Field	Requirement	Description
`bn_session_id` string · path	Required	The BlueNotary session receiving the documents.
`session_documents` array<object>	Required	A nonempty array. Use JSON, not multipart/form-data.
`session_documents[].name` string	Required	A useful file name including the .pdf extension.
`session_documents[].base64Doc` string	Required	Base64 content that decodes to a readable PDF. The example placeholder must be replaced.
`session_documents[].applyTemplate` string	Optional	The saved template ID to apply. Confirm the template and uploaded layout match.
`session_documents[].annotations` array<object>	Optional	Field placement objects. Preview their position and recipient binding before release.
`annotations[].fieldType` string	Conditional	Supported values include signature, initials, date, text, checkmark, and notary-specific fields.
`annotations[].pageNum` integer	Conditional	One-based PDF page number.
`annotations[].x / y / width / height` number	Conditional	Field geometry. Coordinate units and origin require the approved annotation guide. Numeric zero coordinates have a known validation issue; verify the rendered result before releasing documents.
`annotations[].role / signerIndex` string / integer	Conditional	Bind a field to its participant. Notary-specific fields require role "notary". Verify recipient indexing in the annotation recipe.

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/YOUR_SESSION_ID/documents' \
  --header "Authorization: Bearer $BLUENOTARY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "session_documents": [
    {
      "name": "agreement.pdf",
      "base64Doc": "REPLACE_WITH_LOCALLY_ENCODED_PDF"
    }
  ]
}'

Response

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

{
  "response": "Success",
  "response_message": "The Document file is successfully uploaded for the session"
}

The illustrative response shows the success envelope; message text can vary. No document IDs or per-file results are currently returned.
Do not assume atomic batches. A session closing mid-upload can leave previously attached documents in place.
Other file, annotation, or template failures may not always fail the overall response. A generic success does not prove every field was applied.
Published size limits need deployment verification. Logging thresholds are not file-size guarantees.

Errors & recovery

Status	What happened	What to do
400	Invalid or missing document payload	Send a nonempty JSON session_documents array with file names and readable PDF Base64.
403	Session closed for uploads	Do not attach to cancelled, complete, expired, or terminated sessions.
409	Merged document locked	Resolve preparation through the supported workflow before altering the document set.
409	session_closed_partial_upload	Some files are already attached. Inspect stored_documents_count and reconcile before retrying.

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

Handle partial outcomes

When closure interrupts a batch, the response can include response "Partial", error_reason "session_closed_partial_upload", stored_documents_count, and requested_documents_count.

Previously stored documents remain attached.
Do not automatically replay the entire array after an ambiguous timeout or partial result.
Keep your own upload intent and correlation records while verifying the resulting document set.

Keep building

Need help with your implementation?Visit the help center