API Reference

Actions Overview

These are the only four gateway routes the Dispatcher exposes. There is no separate action for sending a document for signature or for approval - Generate Document is the one universal rendering action, and the templateSettings you send in the request body determines whether it also starts an e-signature or approval workflow. There is also no connection health-check action on the gateway route prefix - the Dispatcher's health endpoint (GET /healthz) lives outside /gateway/v1 and is not exposed as a connector action.

Generate Document

Renders a PDF from a template and a JSON data payload stored in SharePoint. Returns the PDF binary directly, plus response headers with the blob path and, when a workflow is configured via templateSettings, a workflow ID for tracking progress.

Request Parameters

Options

The options object controls document identity, classification, and which REFRACT Platform features are activated for this render. All sub-fields are optional.

Feature Flags

Pass any combination of boolean flags inside options.features. Unknown flags are forwarded to the Dispatcher and ignored if not supported.

Template Settings

{
  "workflow": {
    "enabled": true,
    "recipients": [
      {
        "email": "approver@contoso.com",
        "displayName": "Finance Manager"
      }
    ],
    "organizationName": "Contoso",
    "message": "Please review and approve this document.",
    "expiresInDays": 1,
    "requireOtp": false,
    "appendElectronicEvidence": true
  }
}

{
  "esign": {
    "enabled": true,
    "signingMode": "sequential",
    "expiresInMinutes": 10080,
    "signers": [
      {
        "slotIndex": 0,
        "role": "Signer",
        "email": "signer@example.com",
        "namePrefill": "Jane Smith"
      }
    ],
    "requestedByEmail": "jane.smith@contoso.com",
    "sendPerSignerNotices": true
  }
}

{
  "watermark": {
    "enabled": true,
    "value": "CONFIDENTIAL",
    "opacity": 0.1
  }
}

Parameters in Power Automate

Full Request Example

{
  "templatePath": "DynamicsGP/Workflows/vendor-onboarding.rpkg",
  "payloadPath": "DynamicsGP/Workflows/vendor-onboarding-payload.json",
  "templateSettings": {
    "workflow": {
      "enabled": true,
      "recipients": [{ "email": "ap@contoso.com", "displayName": "Acme AP" }],
      "organizationName": "Contoso",
      "message": "Please complete vendor onboarding. Account: Vendor_106",
      "expiresInDays": 1,
      "requireOtp": false,
      "appendElectronicEvidence": true
    }
  },
  "options": {
    "documentId": "Vendor_107",
    "sourceSystem": "DynamicsGP",
    "docType": "workflow",
    "generatedBy": "erp-service@contoso.com",
    "customColumns": { "vendorId": "Vendor1001", "vendorName": "Jane Smith" },
    "features": {
      "generatedDocuments": true,
      "auditSnapshot": true,
      "dataRedaction": true,
      "explainDocument": true,
      "vaultESign": true,
      "immutableAudit": true,
      "vaultDelivery": true
    }
  }
}

Response

Generate Document returns the PDF binary directly - not JSON. Metadata is in the response headers.

Power Automate may normalize header name casing in the outputs()?['headers'] object - if an expression above does not resolve, check the actual header keys in the flow's run history and match them exactly.

The response body is the PDF binary ($content-type: application/pdf). You can pass it directly to Send an email (as attachment) or Create file (SharePoint/OneDrive) actions.

Blob path:   outputs('Generate_Document')?['headers']['X-Refract-BlobPath']
Workflow ID: outputs('Generate_Document')?['headers']['X-Refract-WorkflowId']

Error Responses

The 4xx answers above carry a JSON body, { "error", "code", "message", "correlationId" }, and nothing is rendered or stored for them. Generate Document runs the same rendering logic as /api/render, so it answers with the same codes; see Error responses and codes for every code, its meaning, and whether to retry.

A failure with a PDF body (a 500, or the workflow 422) returns an error report, and these headers say why without opening it:

X-Refract-BlobPath means the stored document. Some error-report 500 responses still set it to the error report's location for one release so that older flows keep working; read X-Refract-ErrorReportPath instead.

Handling Errors in a Flow

A 4xx or 5xx answer fails the Generate Document action. To handle it, add a step after Generate Document and set its Configure run after to has failed, then read the failure from the action's outputs:

Status:        outputs('Generate_Document')?['statusCode']
Refusal code:  body('Generate_Document')?['code']
Error code:    outputs('Generate_Document')?['headers']['X-Refract-ErrorCode']
Correlation:   outputs('Generate_Document')?['headers']['X-Refract-CorrelationId']

Use the refusal code for a 4xx with a JSON body, and the error code for a response with a PDF body. A request problem gets the same answer if the flow sends the same request again, so route it to whoever owns the template or the payload rather than retrying. Keep the correlation ID with any 500 you report.

Send the request again only when body('Generate_Document')?['retryable'] is true, after the number of seconds in outputs('Generate_Document')?['headers']['Retry-After']. Power Automate's default retry policy resends every 5xx, and a resent 500 renders and stores the document again, so set the Generate Document action's retry policy to None and retry from the flow instead. When to retry has the full rule.

Get Document URL

Despite its name (operationId: GetDocumentUrl, inherited from an earlier design where this action returned a link), this action streams the raw bytes of a document stored in Blob Storage directly - it does not return a URL. Pass the blob path returned by Generate Document.

Parameters

Response

A 200 response returns the raw document bytes. Content-Type and Content-Disposition are set from the blob's own metadata. There is no url field and no JSON envelope on success.

Pass the response body directly to Create file (SharePoint/OneDrive) or Send an email (as an attachment) - there is no separate link to fetch or store, and nothing expires the way a signed URL would.

Error Responses

Check Workflow Status

Returns the current state of a document workflow. Poll this action and compare the state field to the terminal value(s) you care about (typically complete, rejected, or cancelled), then call Download Sealed PDF once state is complete.

Parameters

Response

{
  "workflowId": "a3f8c201-d4e9-47b2-91c3-556677880001",
  "correlationId": "6f1e2b3c-7a4d-4e51-9b2f-8c31a0e5f9d0",
  "tenantId": "c49962a1-53d3-4af8-8d5d-35f34cd0be9c",
  "state": "pending-approval",
  "currentStepIndex": 1,
  "totalSteps": 2,
  "title": "Vendor Onboarding Workflow",
  "createdAt": "2026-06-01T14:02:11Z",
  "updatedAt": "2026-06-02T09:15:44Z",
  "data": {}
}

Workflow States

state is one of exactly these thirteen values:

Recommended Polling Strategy

Error Responses

Download Sealed PDF

Streams the raw bytes of the completed, countersigned PDF. Only available once state is complete on Check Workflow Status.

Parameters

Response

A 200 response returns the raw PDF bytes, with Content-Disposition: attachment; filename="workflow-{workflowId}-sealed.pdf".

Pass the response body directly to Create file (SharePoint/OneDrive) or Send an email (as an attachment).

Error Responses

Authentication Errors

These come from the connector's own script.csx, which acquires a client-credentials token from Azure AD before every request - they occur before the request reaches the Dispatcher.

Frequently Asked Questions