CreateWorkflowReq

Request body for creating a workflow. Pick exactly one creation path — supply either blueprintKey + blueprintVersion (instantiate from a stored blueprint) or listingKey + listingVersion (instantiate from a library listing). Combining both shapes returns 400.

blueprintKey
Type: string

Key of the stored blueprint to instantiate, in the same namespace as this request. Required for the blueprint creation path; mutually exclusive with listingKey. To instantiate a blueprint from a different namespace (either elsewhere in your org or in another org), use listingKey instead — the publisher must have published it as a library listing.
blueprintVersion
Type: string

Version of the blueprint to instantiate (semver, e.g. 1.2.0). Required when blueprintKey is supplied.
data
Type: object

Entity payload, keyed by the blueprint's input keys. Each entry is validated against the schema declared on the corresponding blueprint input.
- propertyName
  Type: object
description
Type: string

Optional human-readable description of the workflow.
listingKey
Type: string

Key of the library listing to instantiate. Required for the listing creation path; mutually exclusive with blueprintKey.
listingVersion
Type: string

Version of the listing to instantiate. Required when listingKey is supplied.
name
Type: string

Optional human-readable name for the workflow. When omitted, defaults to Instance of Blueprint - <blueprintKey>@<blueprintVersion> for the blueprint creation path, or Instance of Library Listing - <listingKey>@<listingVersion> for the listing creation path. The default is unambiguous (key + version pin the source) but unfriendly — most callers override it with a transaction-specific name like "Offer letter — Alex Rivera".
options
Type: object

Optional creation-time settings — per-step completion redirects, notification toggles, participant overrides, sender-info overrides, and execution mode.
- disableParticipantNotifications
  Type: boolean
  
  Defaults to false — SignStack sends a signing-link email to each participant when their step starts. Set to true to suppress those emails when your application surfaces the signing experience itself, typically when embedding <ss-signing-embed> inside your own product, or when you're notifying participants through your own channel (in-app notification, your own transactional email, etc.) and don't want the SignStack-branded email going out alongside it.
- mode
  Type: string enum
  
  Run (default) starts execution after creation. Review creates the workflow in pending status without auto-executing — useful for previews where the caller wants to inspect or edit the workflow before kicking it off.
  
  values
  Run
  Review
- senderInfoOverrides
  Type: object
  
  Override the sender block on this workflow's participant emails. Use for white-labeling: surface a different brand on the email a participant receives without changing your namespace's defaults. When supplied, the full block replaces the namespace-level sender info — supply all four required fields together (the technical senderEmail envelope address is always taken from the namespace and cannot be overridden here).
- stepRedirects
  Type: array object[] · WorkflowStepRedirect[]
  
  Optional per-step completion redirects. Each entry sends the participant of one step to a custom URL the moment they finish signing that step, replacing the default SignStack completion screen. Use this to return signers to your own application (an order-status page, a thank-you page, the next task in your flow) instead of leaving them on SignStack.
  
  When the referenced step completes, SignStack appends the step-completion context to your URL as query params, mirroring the step.completed webhook so a receiving page gets the same signal whether it listens on webhooks or the redirect: ?workflowId=<id>&stepKey=<key>&eventType=step.completed. When the namespace has a webhook endpoint the redirect is also signed — SignStack appends timestamp and signature (an HMAC-SHA256 hex digest keyed by your webhook signing secret), so you can verify server-side that the redirect really came from SignStack and reject replays; with no webhook endpoint the redirect is unsigned. Any query params already on the configured URL are preserved.
  
  Applies to SignStack-hosted signing only. Embedded signing (<signstack-participant>) does not apply these redirects — drive post-signing navigation yourself by listening for the component's signed event.
  
  Validated at creation against the resolved blueprint: every stepKey must reference a participant step that exists in the blueprint's orchestration (group steps are rejected — they have no single participant to send anywhere), and each stepKey may appear at most once. Violations return 400.
  
  Maps one participant step to the URL its signer is redirected to right after they finish that step. See CreateWorkflowReq.options.stepRedirects.
- timezone
  Type: string
  
  IANA timezone every date on this workflow's documents renders in.
  
  Defaults to the namespace timezone, which is correct unless this particular agreement belongs somewhere else — a US company signing a lease in Berlin wants the Berlin date on the document, not their own.
  
  Frozen at creation. Whatever resolves here is copied onto the workflow and used for every document it renders. Changing the namespace timezone afterwards does not move dates on workflows already in flight, so a signer never sees a date change between opening a document and signing it. It is returned on GET /workflows/{id} as timezone.
  
  Must be a Region/City IANA name, or UTC. Ambiguous abbreviations (EST, PST) and fixed-offset zones (Etc/GMT+8) are rejected with 400, because they do not observe daylight saving and would render dates an hour out for part of the year.