VaultWorkflow API Reference

All VaultWorkflow endpoints are hosted on the Dispatcher Azure Function. Initiator routes require a valid Entra ID JWT. Participant portal routes use a short-lived portal access token (HMAC-signed, 4-hour TTL) issued at session creation.

Create Workflow Session

POST /api/workflow

Creates a new workflow instance and returns a portal URL for the participant.

Auth: Entra ID JWT (initiator)

Request body:

{
  "templatePath": "templates/vendor-onboarding.vpdf",
  "correlationId": "vc-2026-0601-acme",
  "templateSettings": {
    "workflow": {
      "schemaPath": "Workflows/vendor-onboarding.yaml",
      "recipients": [
        { "email": "[email protected]", "displayName": "Vendor Contact" }
      ],
      "requireOtp": false,
      "organizationName": "Contoso Ltd",
      "message": "Please complete the vendor onboarding form."
    }
  },
  "options": {
    "documentId": "VENDOR-2026-001",
    "docType": "vendor-contract"
  }
}

Response 201:

{
  "workflowId": "a3f1c2d4-8e9b-4f0a-b2c3-1d4e5f6a7b8c",
  "correlationId": "vc-2026-0601-acme",
  "state": "in-progress",
  "portalUrl": "https://portal.vaultpdf.io/workflow/a3f1c2d4-8e9b-4f0a-b2c3-1d4e5f6a7b8c?pt=<portalToken>"
}

Get Workflow (Portal Bootstrap)

GET /api/workflow/{workflowId}

Returns the workflow instance, schema, and current step state for the participant portal.

Auth: Portal access token (query param ?token=<portalToken>)

Response 200: Full WorkflowPortalPayload including schema steps, current data snapshots, and validation state.

Submit Step

PATCH /api/workflow/{workflowId}/step/{stepIndex}

Saves the participant's field data for a single step. Can be called multiple times before the step is submitted.

Auth: Portal access token

Request body:

{
  "data": {
    "vendor_name": "Contoso Supplies Ltd",
    "invoice_total": 47500,
    "payment_terms": "net30"
  }
}

Response 200: Updated step entity.

Advance Step

POST /api/workflow/{workflowId}/advance

Marks the current step as submitted and advances to the next step. When called on the final step, triggers schema validation. If validation passes, the workflow transitions to pending-approval.

Auth: Portal access token

Response 200:

{
  "state": "pending-approval",
  "validationOutcome": "passed",
  "validationResults": []
}

On validation failure:

{
  "state": "validation-failed",
  "validationOutcome": "failed",
  "validationResults": [
    {
      "ruleId": "po_amount_match",
      "passed": false,
      "severity": "error",
      "message": "Invoice total exceeds the approved PO amount.",
      "fieldKey": "invoice_total"
    }
  ]
}

Approve Workflow

POST /api/workflow/{workflowId}/approve

Records the approver's decision and enqueues the seal message. The workflow transitions to sealing.

Auth: Entra ID JWT (approver)

Request body:

{
  "comment": "Approved — within budget and policy."
}

Response 200:

{ "state": "sealing", "workflowId": "a3f1c2d4-8e9b-4f0a-b2c3-1d4e5f6a7b8c" }

Reject Workflow

POST /api/workflow/{workflowId}/reject

Records a rejection decision. No PDF is produced.

Auth: Entra ID JWT (approver or reviewer)

Request body:

{
  "comment": "Vendor not on approved supplier list."
}

Request Changes

POST /api/workflow/{workflowId}/request-changes

Returns the submission to the participant with structured change requests. Workflow transitions to changes-requested.

Auth: Portal access token — issued to the reviewer when the approval notification is sent

Request body:

{
  "changes": [
    {
      "message": "Invoice total does not match attached invoice PDF.",
      "fieldKey": "invoice_total",
      "severity": "error"
    }
  ]
}

Get Workflow Status

GET /api/workflow/{workflowId}/status

Returns the current state, validation outcome, and resolved routing.

Auth: Entra ID JWT (initiator) or portal access token

Response 200:

{
  "workflowId": "a3f1c2d4-8e9b-4f0a-b2c3-1d4e5f6a7b8c",
  "state": "pending-approval",
  "currentStepIndex": 2,
  "totalSteps": 2,
  "validationOutcome": "passed",
  "currentApprovalStage": 0,
  "totalApprovalStages": 1
}

Export Workflow Data

GET /api/workflow/{workflowId}/export?format=json

Exports the complete collected data snapshot. Useful for audit or downstream integrations.

Auth: Entra ID JWT

Query params: format=json (default) or format=csv

Seal Workflow

POST /api/workflow/{workflowId}/seal

Manually enqueues the seal message. Called automatically by the approve endpoint — use this only to retry a failed seal or trigger sealing without the normal approval gate (admin use).

Auth: Entra ID JWT (initiator / admin)

Response 200: { "state": "sealing", "workflowId": "..." }

Fix Validation

POST /api/workflow/{workflowId}/fix-validation

Resets a validation-failed workflow to in-progress at the first failing field's step. Allows the participant to correct data and resubmit without creating a new session.

Auth: Portal access token

Governance Decision

POST /api/workflow/{workflowId}/governance-decision

Records an approver decision on a governance workflow — Approve, Approve with Exception, or Reject. The request includes the decision and (for exceptions) a mandatory justification text.

Auth: Portal access token (reviewer)

Request body:

{
  "decision": "approve-with-exception",
  "justification": "Invoice exceeds PO by 1.6% — within tolerance; approved."
}

Resend Invitation

POST /api/workflow/{workflowId}/resend-invite

Re-sends the workflow invitation email to the current pending approver or participant. Subject to portal-side rate limiting.

Auth: Portal access token

Escalate Workflow

POST /api/workflow/{workflowId}/escalate

Manually escalates the workflow to the next approver in the routing sequence. Normally triggered automatically via escalateAfterDays; this endpoint allows manual escalation.

Auth: Entra ID JWT (initiator)

OTP — Send Code

POST /api/workflow/{workflowId}/otp/send

Sends a one-time passcode to the participant's email. Only valid when requireOtp: true.

Auth: Portal access token. Rate-limited to one send per 60 seconds.

OTP — Verify Code

POST /api/workflow/{workflowId}/otp/verify

Verifies the participant's OTP code.

Auth: Portal access token

Request body: { "otp": "483921" }

OTP constraints: 6 digits, 10-minute TTL, 5-attempt lockout.