Create Workflow

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.

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

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.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.

Request body

FieldTypeConstraints
namestringRequired. 1-255 characters. Leading and trailing whitespace is trimmed.
descriptionstring | nullOptional. Up to 255 characters.
template_version_idstringRequired. 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.
variablesobjectOptional. Default template variable values applied to contract requests created from this contract flow.
participantsarrayRequired, at least one entry. Participant role definitions. Participant key values must be unique.
stagesarrayRequired, at least one entry. Ordered signing and wait stages.
email_notificationsobjectOptional. Per-event email notification, attachment and CC settings. Omitted fields use their defaults.

Participant definition (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), or client_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. null or omitted means no deadline. Not allowed on a participant whose stage uses autosign.

Stage definition (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; either signature (a signature step) or wait_transaction_success (a wait-for-transaction step). At most one wait_transaction_success stage is allowed, and it cannot share its index with any other stage.
  • participant - required for signature stages (the participant key), 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. Either link (the participant signs through a signing link; a client_signing_profile participant is still auto-signed when your signing profile can do so) or autosign (signed automatically with your signing profile). autosign is only allowed for client_signing_profile participants.

Email notifications (email_notifications)

FieldTypeDefaultDescription
invitationbooleantrueSend the signing invitation email when a link participant becomes active.
completedbooleantrueNotify participants when the contract is fully signed.
declinedbooleantrueNotify participants when a signer declines the contract.
expiredbooleantrueNotify participants when the contract expires before completion.
completed_attach_documentbooleantrueAttach the signed contract PDF to the completion email.
completed_attach_audit_logbooleanfalseAttach the signing audit log to the completion email.
completed_extra_emailsarray of emails[]Up to 10 additional addresses that also receive the completion notification, beyond the signers. Duplicates are removed (case-insensitive).
cc_emailsarray 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_daysinteger301-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 role must 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.
  • autosign is only allowed for client_signing_profile participants and cannot be combined with expire_after_hours. If any stage uses autosign, your client must already have a signing profile (see Upsert Signing Profile).
  • link signers that share a stage index sign at the same time and must have the same expire_after_hours value (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

StatusWhen
400The 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)
403Contract signing is disabled for the client
404The referenced template_version_id was not found under this client
422Request 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)
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.

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