How to Delete or deprecate completed Envelope

Question

I have the following scenario:

• Sender "S" creates an envelope for Recipient1 "R1" and Recipient2 "R2" via the API.
• R1 and R2 sign, and the Envelope "E1" is completed.
• Some conditions change in the system, which causes S to send a new envelope to R1 and R2, which contains updated documents of course.
• R1 and R2 sign, and the second Envelope "E2" is completed.

In this scenario E2 should deprecate or even delete E1. The problem is down the line R2 needs to review all the documents he already signed, and it's confusing having both E1 and E2 in the Completed folder.

As far as I know Voiding a Completed envelope is not possible. Ideally I'd like to find a way for S to move E2 to the recycle bin on R2's account.

Answer 1

You should be able to use the "Move Envelope" operation to delete the envelope, as described in on p174 of the REST API guide (http://www.docusign.com/sites/default/files/REST_API_Guide_v2.pdf). According to the guide's description of the Move Envelope operation: "This can be used to delete envelopes by using “recyclebin” as folderId."

UPDATE (Example)

Scenario #1:

• S1 (sender) sends Envelope to 1 recipient -- R1 (recipient #1).
• S1 and R1 are both members within the SAME DocuSign Account. (The "API user" -- i.e., the user that serves as the "Authenticating" user for all API requests -- is also a member of the same Docusign Account. If in your scenario the "Sender" is serving as the "Autheticating" user in all API requests, then you wouldn't necessarily need a separate user/membership for an "API User".)
• R1 signs the envelope. (The Envelope is now Complete.)

Operation A: API request moves the Sender's copy of the Envelope to his Deleted folder.

PUT https://demo.docusign.net/restapi/v2/accounts/{{acctId}}/folders/recyclebin
X-DocuSign-Authentication: {"SendOnBehalfOf":"SenderS1_email@gmail.com","Username":"APIUser_email@outlook.com","Password":"APIUser_Password","IntegratorKey":"IntKey"}
{ 
 "envelopeIds": ["B547562E-5CFC-4989-913E-501CD88F1506"]
}

Note that in the X-DocuSign-Authentication header of the request:

• The "Authenticating" user's credentials (Username, Password) corresponds to the user that has Account-wide-API-rights within that account.

• The value of SendOnBehalfOf corresponds to the Sender's membership email address within that same DocuSign account, and specifies the account to act on.

• If the Sender's credentials are being used as the "Autheticating" user in the API request, then you wouldn't need to include the SendOnBehalfOf property in the X-DocuSign-Authentication header.

RESULT: When S1 logs into the DocuSign web console, he sees that the Envelope now resides in his "Deleted" folder.

Operation B: API request moves the Recipient's copy of the Envelope to her Deleted folder.

PUT https://demo.docusign.net/restapi/v2/accounts/{{acctId}}/folders/recyclebin
X-DocuSign-Authentication: {"SendOnBehalfOf":"RecipientR1_email@gmail.com","Username":"APIUser_email@outlook.com","Password":"APIUser_Password","IntegratorKey":"IntKey"}
{ 
 "envelopeIds": ["B547562E-5CFC-4989-913E-501CD88F1506"]
}

Note that in the X-DocuSign-Authentication header of the request:

• The "Authenticating" user's credentials (Username, Password) again corresponds to the user that has Account-wide-API-rights within that account.
• The value of SendOnBehalfOf corresponds to the Recipient's membership email address within that same DocuSign account, and specifies the account to act on.

RESULT: When R1 logs into the DocuSign web console, she sees that the Envelope now resides in her "Deleted" folder.

NOTE: The most critical component of the "Move (Delete) Envelope" operation working as described above is that the "Authenticating" user for each API request (Username and Password in the X-DocuSign-Authentication header) MUST be a member of the SAME DocuSign Account as the user who's account is being acted upon (i.e., the membership that corresponds to SendOnBehalfOf in the X-DocuSign-Authentication header).