Delayed routing

The delayed routing feature enables you to set a delay between steps of an envelope’s routing order. The routing order defines the sequence in which an envelope is delivered to recipients. If you set a delay for a step in the routing order, the envelope will be placed on hold after all recipients in the previous step complete their required actions, and a delay countdown will begin. When it has elapsed, the envelope will be sent to recipients in the current step of the routing order. You can define the delay as:

• A length of time after the completion of the previous step’s recipient signing process
• An absolute date and time

You can use delayed routing to control the delivery time for recipients at any step in the routing order after the initial send. To set the time for the initial send, use the scheduled sending feature. Another feature enables you to pause envelope delivery before sending to recipients at a step in the routing order, but the pause feature differs from delayed routing and scheduled sending by requiring an API call to resume envelope routing. All three options are part of a suite of eSignature platform features known as Advanced Recipient Routing (ARR).

Note: The delayed routing feature is available in all developer accounts, but only in certain production account plans. Contact Docusign Support or your account manager to find out whether delayed routing is available for your production account plan.

Why delay the routing of an envelope?

By default, completion of the signing process for one step in the routing order causes an envelope to be sent immediately to recipients defined for the next step. However, business needs may require a length of time to elapse before delivery to the next set of recipients. You can set up delayed routing at any step or multiple steps to hold up envelope delivery as needed.

Scenarios in which you can apply delayed routing include:

• You want to delay sending real estate documents to a recipient until the previous signer’s grace period for withdrawing from the deal has expired.
• A recipient needs access to view a document for a length of time before receiving a signable version. You can define the recipient in one step as a carbon copy recipient (with view-only access), while in the next step defining the same recipient as a signer, and add a delay between the two steps.

Add delayed routing to a workflow

You can add delayed routing to the routing order by defining it in an envelope’s or template’s workflow. To implement delayed routing:

1. When you create an envelope or template, add a workflow object.

2. In the workflow object, define one or more workflowSteps objects, each of which represents a step in the routing order.

3. To set a delay before an envelope is routed to recipients at a particular step in the routing order, include a delayedRouting object in the workflowSteps object associated with that step. Several other properties must be defined in the workflowSteps object. They are described in How to send an envelope with delayed routing.

4. In the delayedRouting object, include a rules array.

5. To define when the envelope will be sent to recipients associated with this step in the routing order, in the rules array, add a rule object with one of the following properties:

   • delay: A delay between the completion of the previous step and the time the envelope is sent to recipients in this step. This value is a string in [d.]hh:mm:ss format, defined as:

     • [d]: the number of days from 0 to 30, optional
     • hh: hours from 00 to 23
     • mm: minutes from 00 to 59
     • ss: seconds from 00 to 59

   • resumeDate: A specific date and time when the envelope should be sent to recipients in this step. This value is an ISO8601 datetime string with the time zone specified. For example, 2022-04-03T23:30:00Z represents a send date and time of April 3, 2022 at 11:30 PM UTC. The resumeDate option is not available for templates.

For details and example code, see How to send an envelope with delayed routing.

Delayed routing with bulk sending

Delayed routing supports bulk sending a batch of envelopes to a list of recipients. The general steps for implementing bulk sending with delayed routing are:

1. Define a bulk list of recipients via a request to BulkSend:createBulkSendList.
2. Define a draft envelope or a template that will serve as the basis for the bulk send batch envelopes, including workflow that contains a delay, in an Envelopes:create or Templates:create call.
3. Ensure that the bulk list is compatible with the draft envelope or template by making a request to BulkSend:createBulkSendTestRequest.
4. Correct any issues that the compatibility check finds by updating the envelope, template, or bulk list.
5. Generate the bulk send batch envelopes and send them to recipients in the bulk list by calling BulkSend:createBulkSendRequest.

When a delay has been defined in the workflow, the delay countdown starts and ends independently for each envelope in the batch, once that envelope reaches the step in the routing order that has a delay. For example, if a delay of one day is defined between the first and second step of an envelope’s routing order, and the bulk list consists of two sets of recipients, the batch envelope delays might be processed as follows:

Batch envelope 1

• July 7: Initial send
• July 9: First signer completes envelope and delay starts
• July 10: Delay ends and envelope is sent to second signer

Batch envelope 2

• July 7: Initial send
• July 11: First signer completes envelope and delay starts
• July 12: Delay ends and envelope is sent to second signer

For a walkthrough of the calls to create a bulk send recipient list, apply it to an envelope, and send the batch of envelopes, see How to bulk send envelopes.

Retrieve, update, and delete delayed routing parameters

The EnvelopeWorkflowDefinition resource defines endpoints that you can use to retrieve, update, and delete delayed routing parameters for envelopes and templates.

Cancel a delay

If you attempt to delete delayed routing from an envelope once the delay countdown has begun, you’ll receive an error response. To remove a delay while a countdown is in progress, you can send an EnvelopeWorkflowDefinition:updateEnvelopeDelayedRoutingDefinition request and set the delay or send time to one minute in the future. This will reset the countdown, and the envelope will proceed to the recipients at this step in the routing order one minute later.

Note: Before a delayed routing countdown has begun, you can use the EnvelopeWorkflowDefinition:deleteEnvelopeDelayedRoutingDefinition endpoint or the EnvelopeWorkflowDefinition:deleteTemplateDelayedRoutingDefinition endpoint to remove delayed routing. However, the workflow step that included delayed routing will remain, with a pause_before action. This will cause the envelope to become paused indefinitely at this stage in the routing order, and a call to unpause it will be required. To completely remove any delay or pause between recipients in the routing order, you can use the EnvelopeWorkflowDefinition:deleteEnvelopeWorkflowStepDefinition request or EnvelopeWorkflowDefinition:deleteTemplateWorkflowStepDefinition request instead, as long as the step doesn’t include any other workflow rules that should remain intact.

Behaviors and restrictions

Delayed routing has the following behaviors and restrictions:

• If you define delayed routing for a step in the routing order, the delay applies to all recipients associated with that step.
• Delays can be up to 30 days from completion of the previous step in the routing order. This limit applies to both delays and specific send times. When using a specific send time, the 30-day limit applies to the length of time between completion of the previous step and the resumeDate.
• The delay countdown begins when all recipients associated with a step in the routing order have completed the signing process. For example, if you set a one-hour delay before an envelope is sent to step 2 recipients, the one-hour countdown starts when the last of the step 1 recipients has completed the signing process.
• In a bulk send scenario, a separate delay countdown occurs for each batch envelope. A countdown begins when all of a batch envelope’s recipients associated with a step in the routing order have completed the signing process.
• If you define a specific send time for delayed routing, and the previous step in the routing order is completed after the send time, the envelope will be sent to the current step’s recipients immediately on completion of the previous step.
• If a recipient declines to sign, the envelope will not be routed to any subsequent recipients in the routing order, and any delays associated with subsequent recipients will be ignored.
• If an envelope expires while it is paused prior to sending to the next recipient, it will not be sent.
• If an envelope includes conditional recipient routing as well as delayed routing, and the conditions are not met for an envelope to be delivered to a recipient, any delay associated with that recipient will be skipped and recipient routing will proceed to the next step.
• You can correct an envelope while it’s in a paused status as a result of delayed routing. You can also modify a delay during the paused state.

Envelope statuses

Several types of status are updated as an envelope moves through the delayed routing process. To track envelope status during delayed routing, you may need to check all of these status types:

• Envelope status: The overall envelope status.
• Workflow status: The overall state of the envelope workflow. For more information, see Envelopes:get, scroll down to the Responses section, and on the Definitions tab for a success response, expand the workflow object.
• Workflow step status: Indicates whether a step is currently being executed. For more information, see Envelopes:get, scroll down to the Responses section, and on the Definitions tab for a success response, expand the workflowstep object.
• Delayed routing status: Indicates whether the delay countdown for a step in the routing order is in progress. For more information, see Envelopes:get, scroll down to the Responses section, and on the Definitions tab for a success response, expand the delayedrouting object.

Workflow and delayed routing statuses are not included in Connect messages. To determine the current status, you can use the following calls:

• EnvelopeWorkflowDefinition:getEnvelopeDelayedRoutingDefinition: Returns delayed routing status for a workflow step.
• EnvelopeWorkflowDefinition:getEnvelopeWorkflowStepDefinition: Returns workflow step and delayed routing status for a workflow step.
• Envelopes:get: If you specify an include query parameter with a value of workflow, this call returns the workflow, workflow step, and delayed routing statuses for an envelope, in addition to the envelope status. If you omit the include query parameter, this call does not return workflow, workflow step, and delayed routing information.
• EnvelopeWorkflowDefinition:getEnvelopeWorkflowDefinition: Returns the workflow, workflow step, and delayed routing statuses for an envelope.

Note: Do not call these methods more than once every 15 minutes. Making excess calls to check envelope status will violate Docusign polling rules and can increase your risk of being locked out for exceeding API call limits.

Status changes during delayed routing

Docusign applies the following statuses to envelopes at each stage of delayed routing processing.

Delayed routing status for bulk send batch envelopes

For a delayed routing workflow with a bulk send batch, status changes associated with the start and end of a delay are applied to the batch envelopes, but not to the original draft envelope that served as the basis for the batch envelopes. The original draft envelope remains in a created status with a workflow step status and delayed routing status of pending. See BulkSend Resource for a list of API calls that return information about batch envelopes and their statuses.

Delayed routing status change example with two delays

Below is an example of part of a JSON response to an Envelopes:get call that shows the envelope, workflow, workflow step, and delayed routing statuses. In this example, the routing order consists of three steps with delays before sending envelopes to recipients in the second and third steps.

{
"status": "sent",
"workflow": {
"resumeDate": "2022-03-03T21:15:04.5872828Z",
"workflowStatus": "paused",
"currentWorkflowStepId": "5e6899dd-xxxx-xxxx-xxxx-3d98645827f9",
"workflowSteps": [
    {
        "action": "pause_before",
        "triggerOnItem": "routing_order",
        "itemId": "2",
        "workflowStepId": "795ee946-xxxx-xxxx-xxxx-19da793518cb",
        "status": "completed",
        "triggeredDate": "2022-03-03T21:04:03.3908285Z",
        "delayedRouting": {
            "status": "completed",
            "resumeDate": "2022-03-03T21:07:03.3596049Z",
            "rules": [
                {
                    "delay": "00:03:00"
                }
            ]
        }
    },
    {
        "action": "pause_before",
        "triggerOnItem": "routing_order",
        "itemId": "3",
        "workflowStepId": "5e6899dd-xxxx-xxxx-xxxx-3d98645827f9",
        "status": "in_progress",
        "triggeredDate": "2022-03-03T21:09:04.6185285Z",
        "delayedRouting": {
            "status": "started",
            "resumeDate": "2022-03-03T21:15:04.5872828Z",
            "rules": [
                {
                    "delay": "00:06:00"
                }
            ]
        }
    }
]
},

In a delayed routing scenario consisting of three steps with delays before the second and third steps, the complete list of status changes is:

Error codes

Docusign returns the following codes to report errors related to delayed routing. The API returns the upper-case error code and the message text.

Next steps

For details and example code that demonstrates how to delay routing for an envelope, see:

• How to send an envelope with delayed routing

For information about delaying routing for an envelope in the eSignature web application, see:

• Add Delays Between Recipients in a Routing Order

For more features of Advanced Recipient Routing, see:

• Scheduled sending
• How to schedule an envelope
• Pause and unpause a signature workflow
• How to pause a signature workflow
• How to unpause a signature workflow
• Specify conditional recipients
• How to use conditional recipients

For information about bulk sending, see:

• Bulk sending envelopes
• How to bulk send envelopes