Update Workflow

Update signing workflow

Replaces the workflow's definition (participants, stages, variables,
email notifications) and, if needed, its template. The definition is
validated on save and the workflow stays usable immediately. Returns 404
if the workflow or the new template does not exist, and 400 if the
definition is invalid.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

Replace the full configuration of an existing contract flow. The endpoint overwrites the flow's name, description, linked template version, default variables, participants, stages, and email notification settings, then returns the updated contract flow. The update takes effect immediately: the flow's status is set to published and its definition is replaced in the same call. There is no separate publish step, and any contract request created after this call uses the new definition right away.

Authentication & access

  • Requires a client API token: Authorization: Bearer <token>.
  • API credentials need the contracts.workflows.write permission. Dashboard users need the OWNER or OPERATIONS role, or a custom role that includes this permission.
  • Contract signing must be enabled for the client. If it is disabled the request returns 403.

Path parameters

  • workflow_id (string, required) - the ID of the contract flow to update. Must belong to your client.

Request body

The update replaces the entire contract flow definition - send the complete configuration, not a partial patch.

FieldTypeRequiredNotes
namestringyes1-255 characters. Leading and trailing whitespace is trimmed.
descriptionstringnoUp to 255 characters.
template_version_idstringyesID of the contract template version this contract flow uses. Must belong to your client, be provisioned for signing, and have at least one signer role and one fillable field.
variablesobjectnoDefault template variable values applied to contract requests. Defaults to {}.
participantsarrayyesAt least one participant. Each has a unique key (1-64 chars), a source (user, business_customer, client_signing_profile, or external), a role matching a template signer role (each role can be used by only one participant), optional field_values, optional readonly_fields, and optional expire_after_hours (1-2160; null means no deadline; not allowed on autosign participants). Participant key values must be unique.
stagesarrayyesAt least one stage. Each has an index, a type (signature or wait_transaction_success), and for signature stages a participant key and a delivery type (link or autosign). wait_transaction_success stages must not set participant or delivery. Stage indexes start at 1 and must be gapless; stages that share an index run at the same time. Each participant can appear in at most one signature stage, and autosign is only allowed for client_signing_profile participants.
email_notificationsobjectnoPer-event toggles invitation, completed, declined, expired, and completed_attach_document (default true), completed_attach_audit_log (default false), completed_extra_emails (up to 10), cc_emails (up to 10 view-only recipients), and cc_view_link_days (1-365, default 30). Omitting it resets every setting to its default.

See Create Workflow for the full participant, stage and email_notifications reference.

A body that violates these constraints is rejected with 422.

Behavior

  • The new definition is validated the same way as on Create Workflow, including the template readiness check against the signing service. If any stage uses autosign, your client must have a signing profile. A definition that fails validation returns 400 and the contract flow is left unchanged.
  • The status is always set to published. Updating an archived flow therefore also restores it, the same as Unarchive Workflow.
  • published_at keeps its original value.
  • Contract requests already created from this flow keep the definition they were created with.

Response

200 OK with the full updated contract flow, including its id, name, description, template_version_id, status (always published), variables, participants, stages, email_notifications, published_at, created_at, and updated_at.

Error responses

StatusWhen
400The template is not ready (not provisioned for signing, no signer roles, or no fillable fields), or the definition is invalid (see Create Workflow for the rules)
403Contract signing is disabled for the client
404The contract flow or the referenced template version was not found under this client
422Request body failed validation (e.g. duplicate participant keys, stage indexes not gapless from 1, missing required fields, invalid stage shape, expire_after_hours outside 1-2160, more than 10 cc_emails or completed_extra_emails, or cc_view_link_days outside 1-365)
502The signing service returned an error while fetching the template
503The signing service is not configured or is temporarily unavailable

Standard 401 (authentication), 403 (insufficient permission or role), and 429 (rate limit) responses apply to every endpoint and are documented in the Error reference.

Path Params
string
required
Body Params
string
required
length between 1 and 255
length ≤ 255
string
required

ID of the contract template version this workflow uses

variables
object

Default template variable values applied to contract requests

participants
array of objects
required
length ≥ 1

Participant role definitions for this workflow

Participants*
string
required
length between 1 and 64

Unique key identifying this participant within the workflow

string
enum
required

Source that determines who fills this participant role (e.g. client or end user)

Allowed:
string
required
length between 1 and 255

Signer role name as defined in the contract template

field_values
object

Pre-filled field values for this participant

readonly_fields
array of strings

Field names that this participant cannot modify

Readonly Fields
1 to 2160

Hours this participant has to sign once it is their turn; null means no expiration. Not allowed on auto-signing participants.

stages
array of objects
required
length ≥ 1

Ordered signing and wait stages of this workflow

Stages*
integer
required
≥ 1

Sequential stage number, starting from 1

string
enum
required

Stage type — either a signature step or a wait-for-transaction step

Allowed:
length ≤ 64

Participant key assigned to this stage; required for signature stages

SignatureDeliveryType | null

How the signing request is delivered to the participant; required for signature stages

email_notifications
object

Per-event email notification toggles for this workflow

Responses

Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json