REFRACT Dispatcher API

Every REFRACT Platform deployment exposes its rendering, e-signature, workflow, and delivery capabilities through a single customer-hosted Azure Function App: the Dispatcher. All integrations, whether a Power Automate flow, a Postman test, an ERP connector, or a script, ultimately call this same API.

The "REFRACT Dispatcher API" App Registration

Every Dispatcher deployment provisions one Microsoft Entra ID App Registration, named "REFRACT Dispatcher API" by default (infra/deploy.ps1 creates and configures it automatically as part of the Onboarding session phase of the customer deployment guide). This app registration is a resource, not a client: it defines the API surface that other applications request tokens for. It is configured with:

infra/deploy.ps1 creates no client secret for this app, and it needs none: it is only ever the resource. Every caller is a separate app registration with its own credentials, such as a connector app for each source system. See Connect a source system.

Two Ways to Call the Dispatcher

Endpoints

The 100 requests / 60 second rate limit applies only to the four /api/gateway/v1/* routes, keyed per tenant and calling application. /api/render and the batch-dispatch routes are not rate limited.

Every request, regardless of endpoint or auth model, is validated against the same JWT claims:

Status Route

GET /api/render?ping=true (or ?ping=status) returns a status-report PDF describing the health of the Dispatcher. It returns HTTP 200 when the system is healthy and 503 when it is not. A plain GET /api/render with no ping parameter also renders a status PDF, but always returns 200 regardless of health - use the ping parameter for monitoring probes that need the real status code.

Response Headers

Render responses carry X-Refract-CorrelationId. Which other headers are present depends on the request:

The headers a failed render carries are listed under Error Headers.

Earlier Header Names

Before the platform was renamed, the headers above had another prefix with the same <Name>. The Dispatcher no longer sends the earlier names, and Access-Control-Expose-Headers no longer lists them. A reader built on an earlier name (an add-on, a flow built on the earlier Power Platform connector definition, or an older SPFx package) finds nothing under it: read the X-Refract- name.

Request Headers

The signing portal's signed calls to your Dispatcher carry X-Refract-ESign-* request headers. The Dispatcher reads them on POST /api/esign/callback, /api/esign/committed, /api/esign/consent/serve, /api/esign/consent/acknowledge, /api/esign/consent/slot-preview, /api/esign/email, and /api/esign/signer-event. You do not send them yourself, but a gateway or firewall in front of the Dispatcher must pass them through: a call without them is refused with 401.

These headers were named X-VaultESign-<Name>, with the same <Name>. The signing portal sends each under both names, and the Dispatcher reads the X-Refract-ESign- name first, then the X-VaultESign- name.

Errors

Every error code the Dispatcher returns, the retry rule, and the error headers are on Error responses and codes. This section describes how a failed render answers.

A failed POST /api/render answers in one of two ways, and POST /api/gateway/v1/documents/generate answers the same way because it runs the same rendering logic:

• A request problem answers 4xx with a JSON refusal body. The request named or carried something the Dispatcher cannot use, such as a template that is not there or a payload that is not JSON. Nothing is rendered or stored: no error report, no failed-render record, and no error audit event. Sending the same request again gets the same answer.
• A fault of the service answers 500 with an error-report PDF. The Dispatcher could not produce the document for a reason of its own.

Request Problems

A request problem answers with the status below and this body:

{
  "error": "PayloadNotFound",
  "code": "PAYLOAD_NOT_FOUND",
  "message": "The payload file was not found in the payloads library.",
  "correlationId": "3f2c9a1e-7b4d-4c1a-9e2f-5d6b8a0c1e47"
}

code is the stable value to branch on. message is fixed wording for each code: it never contains the path, the templateId, a payload value, or the text of the underlying error. The Dispatcher's log keeps those, under the same correlation ID.

"Not there" means storage answered that the file does not exist. Anything else that stops a file from being read is a fault of the service, below.

The Dispatcher's other refusals, such as ROLE_MISSING (403) or PAYLOAD_PATH_REQUIRED (400, a templatePath with no payloadPath), use the same body.

Faults

A fault of the service still answers 500, with an error-report PDF as the body (Content-Type: application/pdf, Content-Disposition: attachment). Faults include storage that cannot be reached, a throttle that outlasts the Dispatcher's retries, an authentication failure between the Dispatcher and storage, a library with no drive or container configured, and any error the Dispatcher did not expect. The error report describes the failure; the response headers say why without opening the PDF.

Two request problems still answer this way: an image or structured-content asset the template names that cannot be fetched or decoded, and a redaction policy that parses but cannot be applied to the payload.

Two refusals after a successful render also answer with an error-report PDF. The document was rendered and stored, and only the stage after it was refused:

• An eSign or Delivery session refused after the document rendered answers 500.
• A workflow refused after the document rendered answers 422, and X-Refract-BlobPath names the stored document.

If the error report itself cannot be rendered, the 500 body is JSON instead, with "error": "RenderFailed" and "code": "RENDER_FAILED".

Error Headers

On every failed response (status 400 or more), Access-Control-Expose-Headers lists these headers and Content-Disposition, so browser code on another origin can read them.

Handling Errors

Branch on the content type to read the failure, and on the status to decide what to do next:

const res = await fetch(`${dispatcherUrl}/api/render`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify(request),
});

if (res.status === 200) return await res.arrayBuffer(); // the document

const correlationId = res.headers.get('X-Refract-CorrelationId');
const isJson = (res.headers.get('Content-Type') ?? '').includes('application/json');
const failure = isJson
  ? await res.json() // { error, code, message, correlationId }
  : {
      code: res.headers.get('X-Refract-ErrorCode'),
      message: res.headers.get('X-Refract-ErrorMessage'),
      reportPath: res.headers.get('X-Refract-ErrorReportPath'), // null when the report was not stored
      report: await res.arrayBuffer(), // the error-report PDF
    };

if (res.headers.get('X-Refract-LifecycleErrorCode')) {
  // The document was rendered and stored; only the eSign, Delivery, or workflow step after it was refused.
  // Fix what the code names. The document already exists, so a new render stores a second one.
} else if (res.status < 500) {
  // A request problem: resending the same request gets the same answer.
  // Fix the template, the payload, or the request body, using failure.code.
} else {
  // A fault of the service: keep correlationId and the error report for your administrator.
}

Log failure.code and the correlation ID in every case. Support finds the request in the Dispatcher's log by the correlation ID.

Next Steps

• Authentication - The two auth models in detail, and who may call
• Connect a source system - Connector apps for Business Central, Dynamics 365 Sales, Dynamics GP, Power Platform, and scripts
• Error responses and codes - Every error code, the error headers, and when to retry
• Testing with Postman - Step-by-step OAuth 2.0 configuration for manual API testing
• Power Platform Connector Setup - Client-credentials setup for Power Automate and Power Apps
• REFRACT Dispatch API Reference - Batch dispatch lifecycle endpoints