Workflows

A Workflow is a live, stateful instance of a Blueprint. Where a blueprint is the design — generic and immutable — a workflow is one specific execution: real entity data, real participants, real signing events tracked end-to-end.

A workflow is:

Transactional — represents one specific transaction (onboarding Jane Doe, closing the Acme deal)
Stateful — tracks status (Draft, InProgress, Completed, Failed, Voided) and per-step progress
Auditable — immutable event log + versioned entity-data history, every change linked to the step that caused it

Creating a Workflow

A workflow can run against a blueprint published in your namespace, or against one in the Library — pick the source that matches where the blueprint lives:

Source	Field(s) on the request body	Use when
Published in your namespace	`blueprintKey` + `blueprintVersion`	Standard production path — the blueprint is already pushed and live
From the Library	`listingKey` + `listingVersion`	Running directly against a public or org-shared listing

In either case, you also pass data — an object keyed by the blueprint's input keys with the entity payloads.

curl -X POST https://api.signstack.ai/v1/orgs/{orgId}/namespaces/{namespaceKey}/workflows \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "blueprintKey": "employee_onboarding",
    "blueprintVersion": "1.0.0",
    "data": {
      "employee": { "firstName": "Jane", "lastName": "Doe", "email": "jane@example.com" },
      "company":  { "name": "Acme Corp", "hrManager": { "name": "Alice", "email": "alice@acme.com" } }
    }
  }'

For one-off runs (testing, demos, ops kicking off a workflow by hand), Studio's Run action and the CLI's signstack run command both call this same endpoint — useful when you don't want to wire it into your application yet.

Run vs. Review Mode

The create-workflow request takes an optional options.mode that controls whether the workflow actually starts running:

Mode	Behavior
`Run`	Default. The workflow starts executing — first step kicks off, signing emails go out, webhooks fire as events occur.
`Review`	The workflow is instantiated but not started. Participants are resolved, envelopes are rendered, but no notifications are sent.

Review mode is useful when you want a final sanity check before going live: render the actual documents the participants will see, with the actual data, against the actual blueprint version — without committing to the live signing flow.

A workflow created in Review stays paused until you act on it. Inspect the rendered envelopes and resolved participants, apply any in-flight modifications (see below), then start it to transition into Run. Or void it and start over.

In-Flight Modifications

When a workflow is created in Review state, a few things can still change before you start it:

Entity data — PATCH /workflows/{id}/entities updates entity values. Downstream steps see the new data.
Workflow shape — PUT /workflows/{id} accepts updated envelopes, participants, or rootStep. Use this to swap a participant's email before sending, or fix a typo in a custom field, without re-creating the workflow.

These editing surfaces are scoped to the workflow itself — they don't ripple back to the blueprint. The blueprint stays immutable; the workflow is your one-off tweakable copy.

The workflow editor lets you do all of this visually — use it standalone in Studio or embed it in your own app via the <ss-workflow-editor> component.

Participants Resolved from Data

You don't pass participants directly into the create-workflow request. The blueprint declares participants with name/email expressions ($.company.representative.email), and the engine resolves them from the entity data you provided in data. Send the data, get the participants — no separate participant payload.

For testing convenience, options.overrideAllParticipantEmails routes every signing email to a single test address — saves you from having to swap real emails for test ones in the entity data.

Lifecycle and Monitoring

A workflow moves through these states:

Draft → InProgress → Completed
                 ↘ → Failed
                 ↘ → Voided

Draft — Created but not started (typical for Review mode or before the first step is processed).
InProgress — Engine is executing steps. Participants have been notified or signing actions are in flight.
Completed — Every required step has finished successfully.
Failed — A step's validate expression rejected, or a hard error occurred.
Voided — Cancelled. Either explicitly via POST /workflows/{id}/void, or when a signer declines through the signing flow.

To watch progress, poll GET /workflows/{id} or — preferred — subscribe via webhooks for push notifications as events happen.

Blueprints — The design every workflow runs from
The Workflow Engine (Steps) — Deep dive on how steps execute, branch, and update data
Library — Running workflows directly from listings via listingKey/listingVersion
Webhooks — Real-time event notifications

Blueprints

Schemas