# Create Notarization Request Create a notarization request to connect with a notary and complete online notarizations for your signers within minutes. > ๐Ÿšง **Important:** This endpoint supports only documents in draft status. ## Prerequisites > ๐Ÿšง Before you start > > Ensure the following before creating a notarization request: > > - Install the Notary On-Demand or Notary add-on > - Create a document for notarization and get its `document_id`. To create a document, use the [Create Document from Template](https://developers.pandadoc.com/reference/create-document-from-pandadoc-template) or [Create Document from File Upload](https://developers.pandadoc.com/reference/create-document-from-pdf) endpoint. ## Request Details For the notarization request, include in the request body: - `document_id` - At least one `invitees`, specifying their `email`, `first_name`, and `last_name` - Optionally, include a `message` for your signers - Optionally, using `disable_invitees_notifications` you can disable all notifications for invitees including email with invitation for notarization. This is useful when you are using alternative delivery methods. - If in-house notary must be assigned to this request, include the `notary` object with the notary's `id`, `scheduled_at` timestamp, and an optional `message` for the notary After the API call is executed, your signers will receive an email invitation for notarization. Alternatively, you can directly share the `notarization_link` with your signers, which is available in the 201 response body. Upon successful notarization, you will receive an email with a link to the notarized document. ## Usage Tips > ๐Ÿ“˜ Best Practices > > - Ensure that signers are added as both invitees in the request body and recipients in the document to avoid inconveniences during notary sessions > - Signers will receive an email with a notary link upon a successful API call; this link is also in the 201 response > - In case if notary is not specified in the request, signers will use the link to connect with commissioned online notaries, available Mon-Fri, 9 AM - 9 PM Central Time, typically responding within 2 minutes > - If notary is specified, signers will use the link to connect with your in-house notary at the scheduled time ## Limits A maximum of 100 API calls per minute is permitted. Exceeding this limit triggers a 429 Too Many Requests error. ## Troubleshooting **Solutions for 4xx Response Codes:** - **403 Forbidden (Inactive Add-on)**: Ensure the Notary On-Demand or Notary add-on is installed - **403 Forbidden (Transactions Limit)**: Purchase additional transactions either through the Notary UI or by contacting the Sales team - **429 Too Many Requests**: If you hit the limit, hold your API calls, then send them after waiting for the retry time > ๐Ÿ“˜ To learn more about PandaDoc Notary On-Demand, visit our [website](https://notary.pandadoc.com/notary-on-demand/). # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "PandaDoc Public API", "description": "PandaDoc API spans a broad range of functionality to help you build incredible documents automation experiences inside your product.\n\nPandaDoc API is organized around REST. Our API has predictable resource-oriented URLs and uses standard HTTP response codes, authentication, and verbs.\n\n## Getting started\n\nYou can start testing PandaDoc API with a sandbox key on our [Enterprise](https://www.pandadoc.com/pricing/) plan, either active or in trial.\n\nGenerate your [sandbox key](https://developers.pandadoc.com/reference/sandbox-key) on the Developer Dashboard with predefined [rate limits](https://developers.pandadoc.com/reference/limits). Or contact our solutions expert if you work with high-transaction volumes.\n\n## Guides\n\nIf youโ€™re just getting started with PandaDoc, you may want to jump straight into one of our [getting started guides](https://developers.pandadoc.com/docs/getting-started) for the feature youโ€™re most interested in, whether thatโ€™s:\n\n- [Create from template](https://developers.pandadoc.com/docs/create-send-document),\n- [Upload and send a local PDF](https://developers.pandadoc.com/docs/upload-and-send-a-local-pdf),\n- or [Listening for changes in document status](https://developers.pandadoc.com/docs/listen-document-status-changes).\n\nWe also recommend you to discover our dynamic content generation on a fly: [Create from a template with content placeholder](https://developers.pandadoc.com/docs/create-with-content-placeholders-from-template).\n", "termsOfService": "https://www.pandadoc.com/master-services-agreement/", "contact": { "name": "PandaDoc API Support", "url": "https://developers.pandadoc.com/", "email": "api-track@pandadoc.com" }, "license": { "name": "MIT", "url": "https://github.com/PandaDoc/pandadoc-openapi-specification/blob/main/LICENSE" }, "version": "7.18.2" }, "servers": [ { "url": "https://api.pandadoc.com", "description": "Public API" } ], "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ { "name": "Notary", "description": "Operations for creating and managing notarization requests." } ], "paths": { "/public/v2/notary/notarization-requests": { "post": { "tags": [ "Notary" ], "summary": "Create Notarization Request", "operationId": "createNotarizationRequest", "description": "Create a notarization request to connect with a notary and complete online notarizations for your signers within minutes.\n\n> ๐Ÿšง **Important:** This endpoint supports only documents in draft status.\n\n## Prerequisites\n\n> ๐Ÿšง Before you start\n> \n> Ensure the following before creating a notarization request:\n> \n> - Install the Notary On-Demand or Notary add-on\n> - Create a document for notarization and get its `document_id`. To create a document, use the [Create Document from Template](https://developers.pandadoc.com/reference/create-document-from-pandadoc-template) or [Create Document from File Upload](https://developers.pandadoc.com/reference/create-document-from-pdf) endpoint.\n\n## Request Details\n\nFor the notarization request, include in the request body:\n\n- `document_id`\n- At least one `invitees`, specifying their `email`, `first_name`, and `last_name`\n- Optionally, include a `message` for your signers\n- Optionally, using `disable_invitees_notifications` you can disable all notifications for invitees including email with invitation for notarization. This is useful when you are using alternative delivery methods.\n- If in-house notary must be assigned to this request, include the `notary` object with the notary's `id`, `scheduled_at` timestamp, and an optional `message` for the notary\n\nAfter the API call is executed, your signers will receive an email invitation for notarization. Alternatively, you can directly share the `notarization_link` with your signers, which is available in the 201 response body.\n\nUpon successful notarization, you will receive an email with a link to the notarized document.\n\n## Usage Tips\n\n> ๐Ÿ“˜ Best Practices\n> \n> - Ensure that signers are added as both invitees in the request body and recipients in the document to avoid inconveniences during notary sessions\n> - Signers will receive an email with a notary link upon a successful API call; this link is also in the 201 response\n> - In case if notary is not specified in the request, signers will use the link to connect with commissioned online notaries, available Mon-Fri, 9 AM - 9 PM Central Time, typically responding within 2 minutes\n> - If notary is specified, signers will use the link to connect with your in-house notary at the scheduled time\n\n## Limits\n\nA maximum of 100 API calls per minute is permitted. Exceeding this limit triggers a 429 Too Many Requests error.\n\n## Troubleshooting\n\n**Solutions for 4xx Response Codes:**\n\n- **403 Forbidden (Inactive Add-on)**: Ensure the Notary On-Demand or Notary add-on is installed\n- **403 Forbidden (Transactions Limit)**: Purchase additional transactions either through the Notary UI or by contacting the Sales team\n- **429 Too Many Requests**: If you hit the limit, hold your API calls, then send them after waiting for the retry time\n\n> ๐Ÿ“˜ To learn more about PandaDoc Notary On-Demand, visit our [website](https://notary.pandadoc.com/notary-on-demand/).\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotarizationRequest" }, "examples": { "Create Notarization Request": { "value": { "document_id": "D3okRfgHRX7NEhavcACReB", "disable_invitees_notifications": true, "invitation": { "message": "Your session is ready", "invitees": [ { "email": "signer@example.com", "first_name": "test", "last_name": "test" } ] } } }, "Create Notarization Request with In-House Notary": { "value": { "document_id": "D3okRfgHRX7NEhavcACReB", "disable_invitees_notifications": false, "invitation": { "message": "Your scheduled notarization session", "invitees": [ { "email": "signer@example.com", "first_name": "test", "last_name": "test" } ] }, "notary": { "id": "nyAnVpY7pZ23FBve8s9xgk", "scheduled_at": "2025-09-01T11:00:00Z", "message": "Please review the document before our scheduled session" } } } } } } }, "responses": { "201": { "description": "Notarization request has been created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotarizationResponse" }, "examples": { "Create Notarization Request": { "value": { "id": "f75e053a-25e8-40be-8681-fd755ade2a2b", "name": "test", "status": "SENT", "date_created": "2023-04-14T16:33:06.938984Z", "date_accepted": null, "created_by": { "first_name": "test", "last_name": "test", "email": "user@example.com", "id": "nyAnVpY7pZ23FBve8s9xgk" }, "invitees": [ { "first_name": "test", "last_name": "test", "email": "signer@example.com", "notarization_link": "https://notarize.pandadoc.com/session-request#/?requestId=f75e053a-25e8-40be-8681-fd755ade2a2b&inviteeId=2fbb4cbf-d461-4421-94cf-eaadcb9627e0" } ] } } } } } }, "403": { "$ref": "#/components/responses/403PermissionDeniedV2" }, "429": { "$ref": "#/components/responses/429TooManyRequestsV2" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "name": "Authorization", "in": "header", "description": "The `Authorization` header must contain the API key. The value should be prefixed with `API-Key` followed by a space and the actual API key.\n", "x-default": "API-Key 3039ba033eb1410caa0a2227158d63c9d6502cd8" }, "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://app.pandadoc.com/oauth2/authorize", "tokenUrl": "https://api.pandadoc.com/oauth2/access_token", "refreshUrl": "https://api.pandadoc.com/oauth2/access_token", "scopes": { "read+write": "Use `read+write` to create, send, delete, and download documents, and `read` to view templates and document details." } } }, "description": "Send the authenticating user to the PandaDoc OAuth2 request URL. We recommend a button or a link titled\n\"Connect to PandaDoc\" if you are connecting users from a custom application. Users will see the \"Authorize Application\" screen.\nWhen the user clicks \"Authorize\", PandaDoc redirects the user back to your site with an authorization code inside the URL.\n\nhttps://app.pandadoc.com/oauth2/authorize?client_id={client_id}&redirect_uri={redirect_uri}&scope=read+write&response_type=code\n\n`client_id` and `redirect_uri` values should match your application settings.\n" } }, "schemas": { "CreateNotarizationRequest": { "type": "object", "properties": { "document_id": { "type": "string", "maxLength": 50, "example": "8DstGmLJDBXBKrh3wnqzpe", "description": "ID of the Document for notarization." }, "disable_invitees_notifications": { "type": "boolean", "nullable": true, "default": false, "description": "Disable all notifications for invitees including email with invitation for notarization. This is useful when you are using alternative delivery methods.", "example": true }, "invitation": { "type": "object", "properties": { "message": { "type": "string", "example": "Some message", "description": "Optional message for invitation email." }, "invitees": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255, "nullable": false, "example": "email@gmail.com" }, "first_name": { "type": "string", "maxLength": 50, "nullable": true, "example": "John" }, "last_name": { "type": "string", "maxLength": 50, "nullable": true, "example": "Smith" } }, "required": [ "email" ] } } } }, "notary": { "type": "object", "description": "Optional notary assignment for in-house notary requests. Used for Bring you own notary use case. Only ACTIVE notaries can be used", "properties": { "id": { "type": "string", "description": "ID of an ACTIVE notary", "example": "nyAnVpY7pZ23FBve8s9xgk" }, "scheduled_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp for scheduled notarization", "example": "2025-09-01T11:00:00Z" }, "message": { "type": "string", "description": "Optional custom message for the notary in the invitation email", "example": "Please review the document before the scheduled session" } }, "required": [ "id", "scheduled_at" ] } }, "required": [ "document_id", "invitation" ] }, "CreateNotarizationResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique identifier of the notarization request.", "example": "f75e053a-25e8-40be-8681-fd755ade2a2b" }, "name": { "type": "string", "description": "A name of the notarization request.", "example": "test" }, "status": { "type": "string", "description": "Current status of the notarization request.", "enum": [ "DRAFT", "SENT", "WAITING_FOR_NOTARY", "ACCEPTED", "LIVE", "COMPLETED", "INCOMPLETE", "CANCELLED" ], "example": "SENT" }, "date_created": { "type": "string", "format": "date-time", "description": "A date when a notarization request was created.", "example": "2023-04-14T16:33:06.938984Z" }, "date_accepted": { "type": "string", "format": "date-time", "nullable": true, "description": "A date when a notarization session was accepted by notary.", "example": "2023-04-14T16:33:06.938984Z" }, "created_by": { "type": "object", "properties": { "user_id": { "type": "string", "description": "A unique identifier of the user who created a notarization request.", "example": "nyAnVpY7pZ23FBve8s9xgk" }, "email": { "type": "string", "description": "A user's email address.", "example": "email@gmail.com" }, "first_name": { "type": "string", "description": "A user's first name.", "example": "John" }, "last_name": { "type": "string", "description": "A user's last name.", "example": "Smith" } } }, "invitees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique identifier of the invitee.", "example": "nyAnVpY7pZ23FBve8s9xgk" }, "email": { "type": "string", "format": "email", "maxLength": 255, "description": "A invitee's email address.", "example": "email@gmail.com" }, "first_name": { "type": "string", "maxLength": 50, "description": "A invitee's first name.", "example": "John" }, "last_name": { "type": "string", "maxLength": 50, "description": "A invitee's last name.", "example": "Smith" }, "notarization_link": { "type": "string", "description": "A secure link to join a notarization request.", "example": "https://notarize.pandadoc.com/session-request#/?requestId=f75e053a-25e8-40be-8681-fd755ade2a2b&inviteeId=2fbb4cbf-d461-4421-94cf-eaadcb9627e0" } } } } } } }, "responses": { "429TooManyRequestsV2": { "description": "Too many requests error", "content": { "application/json": { "schema": { "properties": { "code": { "type": "string", "example": "too_many_requests" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "pointer": { "type": "string", "description": "JSON Pointer.", "nullable": true }, "data": { "description": "Details data.", "type": "object", "nullable": true, "minProperties": 0, "additionalProperties": true } }, "required": [ "code" ] }, "example": [] } } } } } }, "403PermissionDeniedV2": { "description": "Permission error", "content": { "application/json": { "schema": { "properties": { "code": { "type": "string", "example": "forbidden" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "pointer": { "type": "string", "description": "JSON Pointer.", "nullable": true }, "data": { "description": "Details data.", "type": "object", "nullable": true, "minProperties": 0, "additionalProperties": true } }, "required": [ "code" ] }, "example": [] } } } } } } } } } ```