Skip to navigation
How-to guidesUse advanced recipient routing

How to send an envelope with delayed routing

View as Markdown
eSignature REST API 2.1 only

This topic demonstrates how to delay an envelope’s delivery between recipients using the delayed routing feature.

Run this code example from our Quickstart or launcher projects: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.

Required data

Running the code in this how-to requires this data:

Data elementDescription
{API_ACCOUNT_ID}A GUID value that identifies your account. This value is automatically generated by Docusign for any account you create. Copy the value from the API Account ID field on the Apps and Keys page.
{BASE_PATH}A string value that forms the root of the URL required to make API calls. The base path value in the example code is set to target the developer environment at
https://<domain>/restapi
Where <domain> is demo.docusign.net for the developer environment and is the result of the GetUserInfo call in production.
{DELAY}The amount of time to delay sending the envelope to the specified recipient represented as a string formatted as a C# TimeSpan constant.
{DOCS_PATH}A string value for the file path to the folder containing the documents you want to include in the envelope.
{DOCUMENT_ID}A document identifier such as a name or ID. You can get a list of envelope documents to obtain this information.
Document to be signedYou must provide at least one document to be signed. Document used in this how-to:
{RECIPIENT_ID}A unique string value that you assign to identify each recipient. This value assigns tabs on a per-recipient basis.
{SIGNER1_EMAIL}A string value for the email address where the first signer will receive a notification of the signing request.
{SIGNER2_EMAIL}A string value for the email address where the second signer will receive a notification of the signing request.
{SIGNER1_NAME}A string value for the full name of the first signer.
{SIGNER2_NAME}A string value for the full name of the second signer.

Step 1. Obtain your OAuth token

To make the API call shown in this how-to, you need a valid OAuth access token. Docusign supports access tokens for three different recommended OAuth grant types: Public Authorization Code Grant, Confidential Authorization Code Grant, and JSON Web Token (JWT) Grant. Choose the OAuth grant type appropriate for your scenario.

See Confidential Authorization Code Grant for guidance on your options to get an Confidential Authorization Code Grant OAuth token.

Three icons that represent the three methods a user can use to obtain an OAuth token: JSON Web Token (JWT), Public Authorization Code Grant (ACG), and Confidential Authorization Code grant

Step 2. Construct the request body

Next, create the request body. Construct an envelope definition with two signers. Set the routing order so that one recipient has a routing order of "1" and the other has a routing order of "2". The delayed routing feature will use the routing order to determine where to add a delay when sending the envelope. Then add the workflowSteps to the envelope definition.

The workflowSteps section describes the delayed routing for one of the recipients in the envelope. In the accompanying code, the action field is set to "pause_before" and the triggerOnItem field is set to "routing_order" with an itemId of "2". DELAY indicates the time lapse after the envelope is sent to the first recipient and before the envelope is sent to the second recipient.

printf \
'{
    "emailSubject": "Please sign this document set",
    "documents": [
        {
            "documentBase64": "' >> $request_data
            cat $doc1_base64 >> $request_data
            printf '",
            "name": "Lorem Ipsum",
            "fileExtension": "pdf",
            "documentId": "1"
        }
    ],
    "workflow": {
        "workflowSteps": [{
            "action": "pause_before",
            "triggerOnItem": "routing_order",
            "itemId": 2,
            "delayedRouting": {
                "rules": [{
                    "delay": "'"${DELAY}"'"
                }]
            }
        }]
    },
    "recipients": {
        "signers": [
            {
                "email": "'"${SIGNER_EMAIL}"'",
                "name": "'"${SIGNER_NAME}"'",
                "recipientId": "1",
                "routingOrder": "1",
                "tabs": {
                    "signHereTabs": [
                        {
                            "anchorString": "/sn1/",
                            "anchorUnits": "pixels",
                            "anchorXOffset": "20",
                            "anchorYOffset": "10"
                        }
                    ]
                }
            },
            {
                "email":  "'"${SIGNER_EMAIL2}"'",
                "name": "'"${SIGNER_NAME2}"'",
                "recipientId": "2",
                "routingOrder": "2",
                "tabs": {
                    "signHereTabs": [
                        {
                            "xPosition": "400",
                            "yPosition": "172",
                            "documentId": "1",
                            "pageNumber": "1"
                        }
                    ]
                }
            }
        ]
    },
    "status": "sent"
}' >> $request_data

Step 3. Call the eSignature REST API

Now that you have constructed your API headers and request body, you can schedule the envelope with the Envelopes:create method. Here’s how you make the call, but make sure to substitute your API account ID for {ACCOUNT_ID}.

View the source code for this how-to on GitHub: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header "Content-Type: application/json" \
     --data-binary @${request_data} \
     --request POST ${base_path}/v2.1/accounts/${account_id}/envelopes \
     --output $response

Expected response

If you run this code example from our Quickstart or launcher projects, you should see a JSON response similar to the code shown.

In addition, the signer receives an email containing a signing link that they can use to open and electronically sign a document using the Docusign mobile app or the Docusign website. After signing is complete, the recipient receives a carbon copy (CC) of the email that includes all of the completed and signed documents.

Sample response
{
    "envelopeId":"ceae82a7-xxxx-xxxx-xxxx-2cba454ad40b",
    "uri":"/envelopes/ceae82a7-xxxx-xxxx-xxxx-2cba454ad40b",
    "statusDateTime":"2022-02-28T23:12:07.9830000Z",
    "status":"sent"
}

Next steps