How to delete and restore an envelope | Docusign

This topic demonstrates how to delete and undelete an envelope. Deleting an envelope in Docusign means to move the envelope into the predefined folder Recycle Bin; undeleting an envelope means to move the envelope out of the Recycle Bin and into another folder as you desire: either another predefined folder, such as Inbox or Sent Items, or into any other folder you’ve defined in your Docusign account.

Docusign also provides other options for removing envelopes: you can void an envelope that’s still in progress (not completed), making it invalid; or you can purge an envelope in any state, which permanently destroys the envelope from your account. Both voiding and purging are one-way operations and cannot be reversed, unlike deleting.

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 element	Description
{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.
{ENVELOPE_ID}	A GUID value that identifies a Docusign envelope. This value is automatically generated by Docusign when the envelope is created.
{FOLDER_ID}	A GUID value that identifies the folder into which you want to move the selected envelope(s). This value is automatically generated by Docusign when the folder is created. For the default Docusign folders Inbox, Sent Items, and Recycle Bin, you can also use the predefined strings “inbox”, “sentitems”, and “recyclebin” , respectively, as folder IDs.

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 your API headers

After you have a valid OAuth access token, you are ready to construct the API headers that you will pass to the API call. Construct your headers like this, but make sure to substitute your valid OAuth access token for {ACCESS_TOKEN}.

declare -a Headers=('--header' "Authorization: Bearer ${ACCESS_TOKEN}"
    '--header' "Accept: application/json"
    '--header' "Content-Type: application/json")

Step 3. Construct the request body

Next, create the request body. The request body for this API call consists of an array of envelope IDs; you can include as many as you wish. For this how-to, view a sample envelope in your developer account (create one if you need to) and select Envelope ID to view the GUID value; then substitute that GUID for {ENVELOPE_ID} in the array.

printf '{
  "envelopeIds": [
    "%s"
  ]
}' "${envelope_id}" > $request_body

Step 4. Call the eSignature REST API to delete your envelope

Now that you have constructed your API headers and request body, make a PUT request to the Folders:moveEnvelopes endpoint and include the request body to specify the envelope to move to the Recycle Bin. Here’s how you make the call, but make sure to substitute your API account ID for {API_ACCOUNT_ID}.

curl --request PUT "${base_path}/v2.1/accounts/${account_id}/folders/recyclebin" \
    "${Headers[@]}" \
    --data-binary @${request_body}

Step 5. Call the eSignature REST API to find the folder id

Find the Destination Folder ID: To restore an envelope to a specific folder, you must first get the folder’s unique ID. You can find this by making a GET request to the Docusign Folders:list API endpoint. This call returns a list of all the folders in your account; each folder’s properties include, among others, its name and corresponding folderId. You can then extract the folderId for the folder you want to move the envelope to; you’ll do that in Step 6.

RESPONSE=$(curl --request GET \
    "${Headers[@]}" \
    "${base_path}/v2.1/accounts/${account_id}/folders")
# Find the specific folder entered and extract its folderId
folder_id=$(echo "${RESPONSE}" | grep -oi "\"name\":\"${destination_folder_name}\",\"type\":\"[^\"]*\",\"owner\":{[^\}]*},\"folderId\":\"[^\"]*\"" | sed 's/.*"folderId":"//' | sed 's/"$//')

Step 6. Call the eSignature REST API to undelete your envelope

Call the Folders:moveEnvelopes method with the ID of the envelope you want to undelete, the folder ID of the folder you want to move it to, and “recyclebin” as fromFolderId. The returned data will include the envelope ID moved from the recycle bin or Deleted folder. Deleted envelopes can be undeleted only within 24 hours from the Docusign Recycle Bin; thereafter, they are no longer accessible from your Docusign account.

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

curl --request PUT "${base_path}/v2.1/accounts/${account_id}/folders/${folder_id}" \
    "${Headers[@]}" \
    --data-raw '{
      "envelopeIds": [
        "'${envelope_id}'"
      ],
      "fromFolderId": "recyclebin"
    }'

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.

Sample response

{
    "envelopes": [
        {
            "envelopeId": "4b0d152e-xxxx-xxxx-xxxx-9d8ada5bdce8"
        }
    ]
}

Next steps

Run this code example from our Quickstart or launcher projects: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.
See how to Go-Live with a completed app and find the base path for API calls in the production environment.