Templates and field placement
Reuse prepared documents or field layouts, and validate programmatic annotations before participants sign.
Choose the right reuse model
A saved document template and a field layout applied to a new PDF solve different problems.
| Input | Purpose |
|---|---|
| document_templates | Select saved document templates for the session. |
| session_documents[].applyTemplate | Apply a template’s fields to an uploaded document. |
| session_documents[].annotations | Provide individual field placements programmatically. |
Use saved document templates
Get the supported template IDs from your business account’s Templates section. API v2 does not expose a template-list endpoint.
- Confirm the template belongs to the intended account.
- Confirm participant roles match the saved fields.
- Review the resulting document before inviting participants.
{
"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"
}
],
"document_templates": [
"YOUR_TEMPLATE_ID"
]
}Apply fields to a new PDF
Supply applyTemplate beside the uploaded file. The new document needs a compatible layout so the saved placements land in the intended locations.
{
"session_documents": [
{
"name": "agreement.pdf",
"base64Doc": "REPLACE_WITH_LOCALLY_ENCODED_PDF",
"applyTemplate": "YOUR_TEMPLATE_ID"
}
]
}A generic upload success does not prove every template or annotation was applied. Missing-template and field-processing failures need explicit verification.
Understand annotation inputs
The mapper uses one-based pageNum and integer coordinate/dimension values. Confirm the coordinate origin and units against the document preview used by your integration before placing production fields.
| Field | Meaning |
|---|---|
| fieldType | Supported field kind, such as signature, initials, text, date, or checkmark. |
| pageNum | The first page is 1. |
| x, y, width, height | Placement rectangle interpreted by the document renderer. |
| role | Participant role; notary fields require notary. |
| signerIndex | Signer mapping; verify the intended recipient in the rendered preview. |
| hint, dateFormat | Optional display/format information for relevant field kinds. |
Numeric zero coordinates can be dropped during field validation. Check the rendered document before release and resolve affected placements with BlueNotary; changing the intended placement is not a reliable workaround.
Select a supported field type
Use only a supported field kind and the right participant role.
- Signer fields: signature, initials, date, text, checkmark.
- Session/notary fields: sessiondate, notary_seal, notary_commission, notary_commission_expiry, notary_state, notary_county, notary_certificate.
- Fields that depend on a notary require the supported notary context.
- Validate unknown types and missing dimensions before sending the request.
Test placement before release
Use representative document layouts, including differing page sizes and multiple signers. Ensure every required field is visible, assigned correctly, and preserved in final output.
- Attach
Upload the document and selected template or annotations.
- Inspect
Review positions and participant ownership in the actual document UI.
- Sign
Complete a test with the intended participant roles.
- Verify
Inspect the final PDF and its artifact mapping.