A workflow is a one-time execution of a blueprint against specific entity data and participants. The blueprint is the reusable definition (envelopes, documents, participants, orchestration steps); the workflow is the actual run — one customer's offer letter going to one buyer and one seller.

Creating a workflow

POST /workflows accepts two shapes — pick one:

1. From a published blueprint: supply blueprintKey + blueprintVersion. The most common path — you authored the blueprint upfront via Studio, CLI, or the resource APIs, and now you're instantiating it for a specific transaction.
2. From a library listing: supply listingKey + listingVersion to instantiate a blueprint published as a library listing by a different namespace (either elsewhere in your org or in another org).

Both shapes also accept data (the entity payload) and optional options (notifications, overrides). Pass an Idempotency-Key header to make POST /workflows safe to retry — a duplicate key returns the originally created workflow rather than creating a new one.

Lifecycle

pending ──Run──▶ in_progress ──▶ completed
                              │
                              ├──▶ failed   (a step errored)
                              ├──▶ declined (a participant declined)
                              └──▶ voided   (Void workflow)

Workflows are mutable execution records — unlike published resources (which are immutable semvers), a workflow's documents, participants, and step tree can be edited via PUT /workflows/{id} while it's still in flight. Once completed, failed, declined, or voided, the workflow is terminal.

State enums (wire values are snake_case):

• Workflow status: pending, in_progress, completed, failed, declined, voided
• Step status: pending, in_progress, completed, skipped, failed
• Envelope status: pending, in_progress, completed, voided, failed
• Participant action status: pending, notified, viewed, signed, declined

Running is asynchronous

The Run workflow endpoint enqueues the workflow for background processing and returns 200 immediately — it does not block until completion. To find out when the workflow finishes, use one of:

• Webhooks (production) — subscribe to workflow.completed, workflow.failed, workflow.declined, workflow.voided (and fine-grained step.* / participant.* / envelope.* events) under the Webhooks tag. This is the recommended path for any production integration.
• Polling status (prototypes / reconciliation) — GET /workflows/{id}/status returns just the current workflow status without the full payload. Use it for prototypes, CLI "wait for completion" flows, or to reconcile after a webhook outage. Don't use it for steady-state monitoring.

Participant signing

Workflows are how you create + run signing processes; the actual participant signing surface (the page where a buyer clicks Sign) is not a public API. Participants reach it via:

• The signing email SignStack sends them (default), or
• The embeddable <ss-signing-embed> component if you're hosting the signing experience inside your own product.

Your code creates and runs the workflow, monitors via webhooks, and surfaces results — humans sign in Studio's signing UI or your embed.