Create signing workflow
Creates a new signing workflow that defines the steps and signer roles for a
contract signing process. The workflow starts in DRAFT status.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Create a reusable signing workflow that defines the participants and the ordered stages (signature steps plus an optional wait-for-transaction step) used to drive a contract signing process. The workflow is created against a published or draft template version and starts in DRAFT status; it must be published separately before it can back a contract request. Returns the persisted workflow, including its generated id, status, and the normalized participant and stage definitions.
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.
Request body
| Field | Type | Constraints |
|---|---|---|
name | string | Required. 1-255 characters. |
description | string | null | Optional. Up to 255 characters. |
template_version_id | string | Required. ID of the template version this workflow uses. The template must exist under your client and must not be archived. |
variables | object | Optional. Default template variable values applied to contract requests created from this workflow. |
participants | array | Required, at least one entry. Participant role definitions. Participant key values must be unique. |
stages | array | Required, at least one entry. Ordered signing and wait stages. |
email_notifications | object | Optional. Per-event email notification and attachment toggles. |
Participant definition (participants[])
participants[])key— required, 1-64 chars; unique within the workflow.source— required; who fills this role (e.g. the client signing identity, an end user, a business customer, or an external signer).role— required, 1-255 chars; signer role name as defined on the template.field_values— optional object of pre-filled field values.readonly_fields— optional list of field names this participant cannot modify.
Stage definition (stages[])
stages[])index— required, starts at 1; stage indexes must be sequential starting from 1.type— required; either a signature step or a wait-for-transaction step.participant— required for signature stages (the participantkey), and must be omitted for wait-for-transaction stages.delivery— required for signature stages, and must be omitted for wait-for-transaction stages.
Behavior
Creation performs lightweight validation only: it checks that the request body is structurally valid and that the referenced template exists and is not archived. Deeper consistency checks (such as participant roles matching the template, delivery method compatibility, and stage limits) are enforced when the workflow is published, not at creation time.
Response
200 OK with the created workflow. The payload includes the generated id, name, description, template_version_id, status (always DRAFT on creation), variables, the normalized participants and stages, email_notifications, and created_at / updated_at timestamps. published_at is null until the workflow is published.
Error responses
| Status | When |
|---|---|
400 | The referenced template is archived and cannot be used for a workflow |
403 | Contract signing is disabled for the client |
404 | The referenced template_version_id was not found under this client |
422 | Request body failed validation (e.g. missing/over-length name, empty participants or stages, duplicate participant keys, non-sequential stage indexes, or a signature stage missing participant/delivery) |
Standard 401 (authentication), 403 (insufficient permission or role), and 429 (rate limit) responses apply to every endpoint and are documented in the Error reference.