Update signing workflow
Updates the configuration of a DRAFT signing workflow. Only workflows in DRAFT
status can be modified.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Replace the full configuration of an existing signing workflow. The endpoint overwrites the workflow's name, description, linked template version, default variables, participants, stages, and email notification toggles, then returns the updated workflow. If the workflow was already published, this edit reverts it to draft and clears its published snapshot, so it must be published again before it can be used in new contract requests.
Authentication & access
- Requires a client API token:
Authorization: Bearer <token>. - The caller must hold the
contracts.workflows.writepermission and have the OWNER or OPERATIONS role. - 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 signing workflow to update. Must belong to your client.
Request body
The update replaces the entire workflow definition — send the complete configuration, not a partial patch.
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | yes | 1–255 characters. |
description | string | no | Up to 255 characters. |
template_version_id | string | yes | ID of the contract template version this workflow uses. Must belong to your client. |
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, optional field_values, and optional readonly_fields. Participant key values must be unique. |
stages | array | yes | At least one stage. Each has an index (sequential, starting at 1), 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 must be sequential starting from 1. |
email_notifications | object | no | Per-event toggles: invitation, completed, declined, expired (default true), and completed_attach_document, completed_attach_audit_log (default false). |
A body that violates these constraints is rejected with 422.
State preconditions & effects
- A workflow in
archivedstatus cannot be updated (400). - The referenced template version cannot be
archived(400). - If the workflow is currently
published, a successful update sets its status back todraftand discards the published snapshot. Re-publish the workflow to make the new configuration usable.
Response
200 OK with the full updated workflow, including its id, name, description, template_version_id, current status, variables, participants, stages, email_notifications, published_at, created_at, and updated_at.
Error responses
| Status | When |
|---|---|
400 | The workflow is archived, or the referenced template version is archived |
403 | Contract signing is disabled for the client |
404 | The workflow or the referenced template version was not found under this client |
422 | Request body failed validation (e.g. duplicate participant keys, non-sequential stage indexes, missing required fields, invalid stage shape) |
Standard 401 (authentication), 403 (insufficient permission or role), and 429 (rate limit) responses apply to every endpoint and are documented in the Error reference.