Skip to navigation
How-to guidesUse advanced recipient routing

How to schedule an envelope

View as Markdown
eSignature REST API 2.1 only

This topic demonstrates how to schedule an envelope using the Scheduled sending 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.
{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.
{SCHEDULED_DATE}The date and time when the envelope will be sent to the signer represented as a string formatted as ISO8601 DATETIME.
{SIGNER_EMAIL}A string value for the email address where the signer will receive a notification of the signing request.
{SIGNER_NAME}A string value for the full name of the 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 one signer. Add a workflow section to the envelope definition. The scheduledSending section of the workflow indicates when the envelope should be sent to the recipient. SCHEDULED_DATE indicates the exact date and time that the envelope will be sent.

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": {
        "scheduledSending": {
            "rules": [{
                "resumeDate": "'"${SCHEDULED_DATE}"'"
            }]
        }
    },
    "recipients": {
        "signers": [
            {
                "email": "'"${SIGNER_EMAIL}"'",
                "name": "'"${SIGNER_NAME}"'",
                "recipientId": "1",
                "routingOrder": "1",
                "tabs": {
                    "signHereTabs": [
                        {
                            "anchorString": "/sn1/",
                            "anchorUnits": "pixels",
                            "anchorXOffset": "20",
                            "anchorYOffset": "10"
                        }
                    ]
                }
            }
        ]
    },
    "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 at the scheduled time 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": "eead435f-xxxx-xxxx-xxxx-25b7d8523d2b",
  "uri": "/envelopes/eead435f-xxxx-xxxx-xxxx-25b7d8523d2b",
  "statusDateTime": "2020-08-18T23:36:26.8830000Z",
  "status": "sent"
}

Next steps