Create signing workflow
Creates a new signing workflow that defines the steps and signer roles
for a contract signing process. The definition is validated on save and
the workflow is usable immediately. Returns 404 if the template does not
exist, and 400 if the template is not ready (no signer roles / fillable
fields) or the definition is invalid.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Create a reusable contract flow 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 flow is validated when it is saved and is created with status published, so it can back a contract request right away. There is no separate publish step. Returns the saved contract flow, including its generated id, status, and the normalized participant and stage definitions.
This endpoint is for contract flows (
/contracts/workflows). Automation workflows (/workflows) are a different resource.
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.
Request body
| Field | Type | Constraints |
|---|---|---|
name | string | Required. 1-255 characters. Leading and trailing whitespace is trimmed. |
description | string | null | Optional. Up to 255 characters. |
template_version_id | string | Required. ID of the template version this contract flow uses. The template must exist under your client, be provisioned for signing, and have at least one signer role and one fillable field. |
variables | object | Optional. Default template variable values applied to contract requests created from this contract flow. |
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, attachment and CC settings. Omitted fields use their defaults. |
Participant definition (participants[])
participants[])key- required, 1-64 chars; unique within the contract flow.source- required; who fills this role:user(an end user),business_customer(a business customer),external(an external signer), orclient_signing_profile(your own signing identity from the signing profile).role- required, 1-255 chars; signer role name as defined on the template. Each template role can be assigned to only one participant.field_values- optional object of pre-filled field values.readonly_fields- optional list of field names this participant cannot modify.expire_after_hours- optional integer, 1-2160 (90 days). Hours the participant has to sign once it is their turn.nullor omitted means no deadline. Not allowed on a participant whose stage usesautosign.
Stage definition (stages[])
stages[])index- required, starts at 1. The distinct stage indexes must be gapless (1, 2, ... M). Stages that share an index run at the same time (parallel signing).type- required; eithersignature(a signature step) orwait_transaction_success(a wait-for-transaction step). At most onewait_transaction_successstage is allowed, and it cannot share its index with any other stage.participant- required for signature stages (the participantkey), and must be omitted for wait-for-transaction stages. Each participant can appear in at most one signature stage.delivery- required for signature stages, and must be omitted for wait-for-transaction stages. Eitherlink(the participant signs through a signing link; aclient_signing_profileparticipant is still auto-signed when your signing profile can do so) orautosign(signed automatically with your signing profile).autosignis only allowed forclient_signing_profileparticipants.
Email notifications (email_notifications)
email_notifications)| Field | Type | Default | Description |
|---|---|---|---|
invitation | boolean | true | Send the signing invitation email when a link participant becomes active. |
completed | boolean | true | Notify participants when the contract is fully signed. |
declined | boolean | true | Notify participants when a signer declines the contract. |
expired | boolean | true | Notify participants when the contract expires before completion. |
completed_attach_document | boolean | true | Attach the signed contract PDF to the completion email. |
completed_attach_audit_log | boolean | false | Attach the signing audit log to the completion email. |
completed_extra_emails | array of emails | [] | Up to 10 additional addresses that also receive the completion notification, beyond the signers. Duplicates are removed (case-insensitive). |
cc_emails | array of emails | [] | Up to 10 view-only (CC) recipients. Each receives a secure read-only link to the contract when it is sent, and the completed, declined and expired notifications according to the toggles above. They cannot sign. Addresses that match a signer are skipped. Duplicates are removed (case-insensitive). |
cc_view_link_days | integer | 30 | 1-365. Days the CC view-only links keep working after the contract is completed, declined or expired. While signing is in progress they always work; canceling the contract closes them at once. |
Behavior
The contract flow is validated when it is saved and can be used immediately:
- The template's latest signer roles and fields are fetched from the signing service, so recent edits in the document builder are taken into account. The template must be provisioned for signing and have at least one signer role and one fillable field.
- Every participant
rolemust exist on the template, and each template role can be assigned to only one participant. - Every signature stage must reference a defined participant
key, and a participant can appear in at most one signature stage. autosignis only allowed forclient_signing_profileparticipants and cannot be combined withexpire_after_hours. If any stage usesautosign, your client must already have a signing profile (see Upsert Signing Profile).linksigners that share a stage index sign at the same time and must have the sameexpire_after_hoursvalue (or all leave it unset). Set the same value on all of them or split them into separate stages.
A definition that breaks any of these rules is rejected with 400 and nothing is saved.
Two things are checked only when a contract is sent from the flow, so a saved flow can still fail at send time with 400: the template must not be archived, and your signing profile must be able to auto-sign (signature image on file, required fields fillable).
Response
200 OK with the created contract flow. The payload includes the generated id, name, description, template_version_id, status (always published on creation), variables, the normalized participants and stages, email_notifications (with defaults filled in), published_at (the creation time), and created_at / updated_at timestamps.
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 (a participant role not on the template, a template role used by more than one participant, a stage referencing an unknown participant, a participant in more than one signature stage, autosign on a participant that is not client_signing_profile or that has expire_after_hours, autosign without a signing profile, more than one wait stage or a wait stage sharing its index, or parallel link signers with different expire_after_hours) |
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, stage indexes not gapless from 1, a signature stage missing participant/delivery, a wait stage that sets them, an unknown source, type or delivery, expire_after_hours outside 1-2160, more than 10 completed_extra_emails or cc_emails, an invalid email address, 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.