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.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
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.writepermission. 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.
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | yes | 1-255 characters. Leading and trailing whitespace is trimmed. |
description | string | no | Up to 255 characters. |
template_version_id | string | yes | ID 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. |
variables | object | no | Default template variable values applied to contract requests. Defaults to {}. |
participants | array | yes | At 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. |
stages | array | yes | At 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_notifications | object | no | Per-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 returns400and the contract flow is left unchanged. - The status is always set to
published. Updating anarchivedflow therefore also restores it, the same as Unarchive Workflow. published_atkeeps 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
| Status | When |
|---|---|
400 | The 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) |
403 | Contract signing is disabled for the client |
404 | The contract flow or the referenced template version was not found under this client |
422 | Request 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) |
502 | The signing service returned an error while fetching the template |
503 | The 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.