v1
latestSwagger 2.02026-07-134146194.6 MBSend, void, or modify a draft envelope. Purge documents from a completed envelope.
This method enables you to make changes to an envelope. You can use it to:
- Send a draft envelope
- Void an in-process envelope
- Modify a draft envelope
- Purge documents and envelope metadata from the Docusign platform
Although the request body for this method is a complete envelope definition, you only need to provide the properties that you're updating.
Sending a draft envelope
To send a draft envelope, include the following code in the request body:
{
"status": "sent"
}
You can attach a workflow before sending the envelope:
{
"status": "sent",
"workflow": {
"workflowSteps": [
{
"action": "pause_before",
"description": "pause_before routing order 2",
"itemId": 2,
"triggerOnItem": "routing_order"
}
]
}
}
Working with workflows
To unpause a workflow, the request body should include this:
{
"workflow": {
"workflowStatus": "in_progress"
}
}
Voiding an in-process envelope
To void an in-process envelope, include the following code in the request body:
{
"status": "voided",
"voidedReason": "The reason for voiding the envelope"
}
Modifying envelope email information
To change the email subject and message of a draft envelope, include the following code in the request body:
{
"emailSubject": "new email subject",
"emailBlurb": "new email message"
}
Purging documents from Docusign
To place only the documents in the purge queue, leaving any corresponding attachments and tabs in the Docusign platform, set the purgeState property to documents_queued.
{
"envelopeId": "222e6847-xxxx-xxxx-xxxx-72a3c9c16fca",
"purgeState": "documents_queued"
}
To place documents, attachments, and tabs in the purge queue, set the purgeState property to documents_and_metadata_queued.
{
"envelopeId": "222e6847-xxxx-xxxx-xxxx-72a3c9c16fca",
"purgeState": "documents_and_metadata_queued"
}
To place documents, attachments, and tabs in the purge queue and to redact personal information, set the purgeState property to documents_and_metadata_and_redact_queued.
{
"envelopeId": "222e6847-xxxx-xxxx-xxxx-72a3c9c16fca",
"purgeState": "documents_and_metadata_and_redact_queued"
}
You can purge documents only from completed envelopes that are not marked as the authoritative copy. The user requesting the purge must have permission to purge documents and must be the sender or be acting on behalf of the sender.
When the purge request is initiated the items to be purged are placed in the purge queue for deletion in 14 days. The sender and all recipients with Docusign accounts associated with the envelope get an email notification the documents will be deleted in 14 days. The notification contains a link to the documents. A second email notification is sent 7 days later. At the end of the 14-day period the documents are deleted from the system. Recipients without Docusign accounts do not receive email notifications.
If your account has a Document Retention policy, envelope documents are automatically placed in the purge queue, and notification emails are sent at the end of the retention period. Setting a Document Retention policy is the same as setting a schedule for purging documents.
Removing documents from the purge queue
To remove documents from the purge queue, include the following code in the request body:
{
"envelopeId": "222e6847-xxxx-xxxx-xxxx-72a3c9c16fca",
"purgeState": "documents_dequeued"
}
Related topics
- Void an envelope (Common API Tasks)
- Purging documents (eSignature Concepts)
- Purging documents in an envelope (blog post)
- How to unpause a signature workflow
Path parameters
The external account number (int) or account ID GUID.
The envelope's GUID.
Example: 93be49ab-xxxx-xxxx-xxxx-f752070d71ec
Query parameters
When true, allows the caller to update recipients, tabs, custom fields, notification, email settings and other envelope attributes.
When true, sends the specified envelope again.
Request body
Response
Successful response.