DocuSign API - Reset/Unlock RecipientAuthenticationStatus - docusignapi

Question

I'm using the DocuSign API to electronically sign documents within my app. I'm using the access code authentication feature, for some additional security; however, I am trying to 'Unlock' a signer (via the API) that has input the wrong access code too many times, without voided and creating a new envelope, or using the DocuSign Admin interface.
I don't care if I have to resend the initial email, I just want to be able to conserve my client's total envelope count. It's also important (if there are multiple signers) that I don't force one signer to have to sign multiple times, if they completed their signatures prior to signer2's authentication error.
I have attempted a POST to:
/v2/accounts/{accountId}/envelopes/{envelopeId}?resend_envelope=true
I have also sought a solution using the docusign-java-client:
Recipients recipients = envelopesApi.listRecipients(accountId, envelopeId);
List<Signer> signers = recipients.getSigners();
for (Signer signer : signers) {
signer.setRecipientAuthenticationStatus(null);
}
I still get the below response
"recipientAuthenticationStatus": {
"accessCodeResult": {
"status": "Failed",
"eventTimestamp": "2018-01-15T23:49:15.8600000Z"
}
I'm able to "Resend" via the DocuSign admin GUI, and everything works as expected...
Is there any way that I'm able "reset/unlock" this authentication feature programatically, through the API?

Answer 1

You can use below PUT endpoint
PUT /restapi/v2/accounts/<accountId>/envelopes/<envelopeId>?resend_envelope=true
Body as:
{
}
This should send another email to the signer who failed the authentication, and that user will again get option to enter the access code.

Answer 2

I think you will need to delete and then re-add the recipient (signer). That makes the signer become a new recipient.
However, doing so means you'll need to re-create everything about the signer: their document tabs/fields, etc.
I can't imagine that it is less expensive to simply void/resend the envelope than to spend a developer's time to work on this issue.
If this scenario is occurring a lot, then perhaps think about providing better training to your signers with respect to using the access code feature.

Answer 3

Per the documentation found here
I must include the json or xml with the request (if the authentication method failed). I assumed incorrectly that if there was only one recipient, then I would NOT have to specify. If you just want to resend the envelope, you don't need to include and signer data.
Such as:
{"signers" :
[{"email":"testEmail#gmail.com",
"name":"FirstName LastName",
"recipientId":"1"
}]
}
You should then get something like the below response:
{"recipientUpdateResults":
[{
"recipientId": "1",
"errorDetails":
{
"errorCode": "SUCCESS",
"message": ""
}
}]
}