VaultDelivery API Reference
HTTP endpoint reference for creating delivery sessions, querying session state, downloading documents, OTP verification, and revoking access.
All VaultDelivery endpoints are hosted on the Dispatcher Azure Function. Initiator routes require a valid Entra ID JWT. Recipient portal routes use a short-lived delivery access token issued at session creation and embedded in the portal URL.
Base URL
All paths are relative to your Dispatcher Function base URL, e.g. https://<your-dispatcher>.azurewebsites.net.
Create Delivery Session
POST /api/deliveryCreates one or more delivery sessions (one per recipient) for a rendered document.
Auth: Entra ID JWT (initiator)
Request body:
{
"correlationId": "rnd-00123",
"documentId": "DOC-456",
"documentName": "Invoice #INV-2026-001.pdf",
"pdfBlobPath": "generatedDocuments/2026/05/rnd-00123.pdf",
"mode": "secure-email",
"recipients": [
{
"email": "vendor@contoso.com",
"name": "Vendor Contact",
"role": "recipient"
}
],
"requesterOrg": "Contoso Ltd",
"message": "Please find your document attached. This link expires in 7 days.",
"expiresInHours": 168,
"requireOtp": false
}| Field | Type | Required | Description |
|---|---|---|---|
correlationId | string | Yes | Correlation ID of the rendered PDF being delivered. Used to link delivery events to the document audit trail. |
documentId | string | No | Document identifier for display purposes. |
documentName | string | Yes | Filename shown to the recipient in the delivery portal and notification email. |
pdfBlobPath | string | Yes | Blob Storage path of the PDF to deliver. |
mode | secure-email | sharepoint | both | Yes | Delivery mode. See Delivery Modes. |
recipients | array | Yes | One or more recipient objects. Max 20 recipients per request. A separate delivery session is created per recipient. |
recipients[].email | string | Yes | Recipient email address. Used for notification and OTP delivery. |
recipients[].name | string | No | Recipient display name used in the notification email. |
recipients[].role | string | No | Role label (e.g. vendor, customer). Recorded in the audit event. |
requesterOrg | string | No | Sender organization name displayed in the notification email. |
message | string | No | Custom message body included in the notification email. |
expiresInHours | number | No | Session TTL in hours. Defaults to 168 (7 days). |
requireOtp | boolean | No | When true, recipient must verify a one-time passcode before downloading. Default false. |
sharePointTarget | object | No | Required when mode is sharepoint or both. See below. |
SharePoint target:
{
"sharePointTarget": {
"siteUrl": "https://contoso.sharepoint.com/sites/Finance",
"libraryPath": "Shared Documents/Invoices",
"folderPath": "2026/May"
}
}Response 201:
{
"sessions": [
{
"deliveryId": "a3f1c2d4-8e9b-4f0a-b2c3-1d4e5f6a7b8c",
"recipient": "vendor@contoso.com",
"portalUrl": "https://portal.vaultpdf.io/deliver/a3f1c2d4-8e9b-4f0a-b2c3-1d4e5f6a7b8c?t=<accessToken>"
}
]
}| Field | Type | Description |
|---|---|---|
deliveryId | string | UUID identifying the delivery session. Use this to query, revoke, or look up the session. |
recipient | string | Recipient email address (echoed from request). |
portalUrl | string | Full portal URL with embedded access token. This URL is emailed to the recipient. Constructed as {ESIGN_PORTAL_API_URL}/deliver/{deliveryId}?t={token}. |
Portal URL is on Vault Shared Services
The portalUrl points to the Vault eSign Portal (portal.vaultpdf.io), hosted on Vault Shared Services. The recipient's browser fetches the document via the Dispatcher's download endpoint - document bytes do not transit the portal. See Data Sovereignty.
Query Delivery Sessions
GET /api/delivery-sessions?correlationId={correlationId}Returns all delivery sessions for a given document correlation ID.
Auth: Entra ID JWT
Response 200:
{
"sessions": [
{
"deliveryId": "a3f1c2d4-8e9b-4f0a-b2c3-1d4e5f6a7b8c",
"correlationId": "rnd-00123",
"documentName": "Invoice #INV-2026-001.pdf",
"state": "downloaded",
"mode": "secure-email",
"expiresAt": "2026-06-16T12:00:00.000Z",
"createdAt": "2026-06-09T12:00:00.000Z",
"openedAt": "2026-06-10T09:14:22.000Z",
"downloadedAt": "2026-06-10T09:15:01.000Z",
"viewCount": 2
}
]
}Get Delivery Session (Portal)
GET /api/delivery/{deliveryId}?t={accessToken}Validates the recipient's access token and returns session metadata for the delivery portal UI. Called by the portal when the recipient opens their link.
Auth: Delivery access token (?t= query parameter, embedded in the portal URL)
Response 200:
{
"deliveryId": "a3f1c2d4-8e9b-4f0a-b2c3-1d4e5f6a7b8c",
"documentName": "Invoice #INV-2026-001.pdf",
"recipientName": "Vendor Contact",
"recipientRole": "recipient",
"requesterOrg": "Contoso Ltd",
"mode": "secure-email",
"sentAt": "2026-06-09T12:00:00.000Z",
"expiresAt": "2026-06-16T12:00:00.000Z",
"state": "opened",
"viewCount": 1,
"requireOtp": false,
"otpVerified": false
}Returns 410 Gone if the session is expired or revoked. The actual document download URL is generated separately via the download endpoint.
Get Download URL
GET /api/delivery/{deliveryId}/sas?t={accessToken}
POST /api/delivery/{deliveryId}/download?t={accessToken}Returns a short-lived SAS URL for the recipient to download the document. Called by the portal after the recipient has opened the document and (if required) passed OTP verification.
Auth: Delivery access token (?t= query parameter)
Returns 403 if requireOtp is true and OTP has not been verified.
Response 200:
{
"sasUrl": "https://<storage-account>.blob.core.windows.net/generatedDocuments/.../Invoice.pdf?sv=...&sig=...",
"expiresAt": "2026-06-09T12:15:00.000Z"
}The SAS URL is short-lived (typically 15 - 30 minutes). The portal streams the document from this URL directly to the recipient's browser - document bytes never transit the portal servers.
Record Access Event
POST /api/delivery/{deliveryId}/access?t={accessToken}Records a portal access event. Called by the delivery portal when the recipient opens the document view.
Auth: Delivery access token
Request body:
{
"eventType": "opened",
"ip": "203.0.113.0"
}| Field | Type | Description |
|---|---|---|
eventType | opened | downloaded | The access event to record. |
ip | string | Recipient IP address forwarded by the portal. |
Response 200: { "ok": true }
Send OTP
POST /api/delivery/{deliveryId}/otp/send?t={accessToken}Sends a one-time passcode to the recipient's email address. Only valid when requireOtp: true was set at session creation.
Auth: Delivery access token
Rate-limited to one send per 60 seconds per session. Returns 400 if OTP is not required for this session or has already been verified.
Response 200: { "ok": true }
Verify OTP
POST /api/delivery/{deliveryId}/otp/verify?t={accessToken}Verifies the one-time passcode entered by the recipient.
Auth: Delivery access token
Request body:
{ "otp": "483921" }| Constraint | Value |
|---|---|
| Code format | 6 digits |
| Code TTL | 10 minutes from send time |
| Max attempts | 5 (session locked after 5 failures) |
Response 200:
{ "ok": true, "verified": true }Returns 400 with details if the code is incorrect, expired, or max attempts exceeded.
Revoke Delivery Session
POST /api/delivery/{deliveryId}/revokeImmediately revokes a delivery session. Any subsequent recipient access attempt returns 410 Gone.
Auth: Entra ID JWT (initiator - must be same tenant as session creator)
Response 200:
{ "deliveryId": "a3f1c2d4-8e9b-4f0a-b2c3-1d4e5f6a7b8c", "state": "revoked" }Track Deliveries in VaultLifecycle
All delivery events are visible in the Delivery tab of the Lifecycle Workspace alongside the full document audit timeline.
VaultDelivery
VaultDelivery provides secure document dispatch and delivery for VaultPDF-generated documents. Send documents to external recipients via time-limited access links or write directly to SharePoint, with full access auditing and proof of delivery.
VaultNotification
VaultNotification is the shared notification layer for the REFRACT Platform. It routes email and SMS notifications for VaultDelivery, VaultESign, and VaultWorkflow through either Vault Shared Services ACS or your own Azure Communication Services instance.