Skip to navigation

Pause and unpause a signature workflow

View as Markdown
eSignature REST API 2.1 only

The Docusign eSignature API lets you customize a signature workflow by pausing and unpausing the signing process. This is one of a suite of eSignature platform features collectively known as Advanced Recipient Routing (ARR).

Why pause and unpause a signature workflow?

Many companies have internal business rules for processes that require signatures. For example, some industries must enforce very prescriptive rules about when certain individuals can sign. Such rules can not only make these processes complex, but also deter businesses from implementing automated signature workflows. The pausing and unpausing features of the eSignature API enable developers to accommodate business rules that affect the timing of signatures in a workflow, thereby making these complex processes amenable to automation.

Among the many use cases for pausing and unpausing a workflow are:

  • Scheduling the sending of envelopes to some subset of recipients at a specific time
  • Enforcing a wait period before a signer can sign
  • Conducting part of a signature workflow outside of Docusign and verifying the external process is complete before continuing the signature workflow
  • Using conditional recipients, another feature of advanced recipient routing (which requires pausing and unpausing the workflow)

How pausing and unpausing works

The eSignature REST API provides an object named workflow that contains the properties of an envelope that enable you to pause or unpause it.

When you create an envelope or template using the eSignature REST API, you can include the workflow object in the envelope definition’s JSON structure to make the envelope’s signature workflow pause at the step you designate.

When the envelope is sent, the properties of the workflow object will trigger a pause when the condition is met such as, for example, before a second signer is prompted to sign. While the envelope is paused, its envelope cannot be signed, and no notifications are delivered for it. Pausing the signature workflow enables a developer to have their integration carry on actions both outside and inside Docusign to fulfill their business process’s requirements before continuing the workflow.

The workflowStatus property is used to unpause the envelope and thereby restart a signature workflow. To do so, make another call to the eSignature REST API and set the workflowStatus property to in_progress in the JSON request body.

See How to pause a signature workflow and How to unpause a signature workflow for detailed walkthroughs of how to pause and unpause your workflows.

Determine whether an envelope is paused

Connect messages do not include an envelope’s workflowStatus indicating whether it is paused or not, but your app can call the EnvelopeWorkflowDefinition:getEnvelopeWorkflowDefinition endpoint (or equivalent SDK method) to manually check. You can also use your recipient statuses to determine whether the envelope should be paused or unpaused.

The following example EnvelopeWorkflowDefinition:getEnvelopeWorkflowDefinition response message shows a sample response indicating that your envelope is paused.

{
"workflowStatus": "paused",
"currentWorkflowStepId": "71d8e564-xxxx-xxxx-xxxx-43c709920db6",
"workflowSteps": [
{
"action": "pause_before",
"triggerOnItem": "routing_order",
"itemId": "2",
"workflowStepId": "71d8e564-xxxx-xxxx-xxxx-43c709920db6",
"status": "in_progress",
"triggeredDate": "2022-01-17T18:29:31.3632611Z"
}
]
}

Note: Do not call the EnvelopeWorkflowDefinition:getEnvelopeWorkflowDefinition method to poll for your envelope’s pause status more than once per every 15 minutes. Making excess calls to check an envelope’s pause status will violate Docusign polling rules and can increase your risk of being locked out for exceeding API call limits.

Next steps

For details and full example code that demonstrates how to pause and unpause a signature workflow, see:

For more features of Advanced Recipient Routing, see: