UNKNOWN_ENVELOPE_RECIPIENT but the recipients actually do match

Question

We’re experiencing this error:

{"errorCode"=>"UNKNOWN_ENVELOPE_RECIPIENT", "message"=>"The recipient you have identified is not a valid recipient of the specified envelope. Envelope recipient could not be determined. 'clientUserId', 'email', or 'userName' in request and envelope may not match."}

However, the signers are identified by either the email field or clientUserId (they’re both the email) and it matches everywhere. I've quadruple checked. So this error just seems plain wrong. This particular request is only failing for one envelope where I’m trying to retrieve an embedded signing experience for a specific user. I can’t replicate the issue with any other envelopes using different email addresses that we have created to try to investigate this issue.

If the user trying to load up the embedded signing experience already had a Docusign account could that effect anything? From what I can tell from my testing, this issue seems like it’s stemming from her email somehow… and appears to be on the Docusign side of things.

UPDATE:

I was being a bit vague on purpose as I am not a fan of disclosing this kind of data publicly. But as you requested, here is the get_recipients return:

pry(main)> client.get_envelope_recipients(envelope_id: 'dffa4edc-1fcf-4098-b3e8-9b1a5ed984f8')
=> {
                "signers" => [
        [0] {
                         "name" => "Bridget C. Shoemaker",
                        "email" => "[email protected]",
                  "recipientId" => "1",
              "recipientIdGuid" => "c8edf6a1-ab19-4bd0-af75-715bcec43aa1",
              "requireIdLookup" => "false",
                       "userId" => "1a873cb0-044a-4b3f-9e0d-dc6a948e579b",
                 "clientUserId" => "[email protected]",
                 "routingOrder" => "1",
                         "note" => "",
                     "roleName" => "Third Party",
                       "status" => "delivered",
            "deliveredDateTime" => "2013-12-09T18:25:44.7800000Z"
        }
    ],
                 "agents" => [],
                "editors" => [],
         "intermediaries" => [],
           "carbonCopies" => [],
    "certifiedDeliveries" => [],
        "inPersonSigners" => [],
         "recipientCount" => "1",
    "currentRoutingOrder" => "1"
}

And here is the get_recipient_view request body in JSON format for the REST API

{\"authenticationMethod\":\"email\",\"clientUserId\":\"[email protected]\",\"email\":\"[email protected]\",\"returnUrl\":\"https://app.bolstr.com/accredited_verifications/113/docusign_response?accredited_verification_id=113\",\"userName\":\"Third Party Verification\"}

Dam

Answer 1

Troubleshooting this issue should be simple if you can update your Question with the following information:

• The Response you receive when you execute a "Get Recipients" request for the Envelope (GET /accounts/{accountId}/envelopes/{envelopeId}/recipients)

• The JSON or XML that you're using for your "POST Recipient View" request (POST /accounts/{accountId}/envelopes/{envelopeId}/views/recipient).

If you can update your Question to include this information, I will update my answer to provide info about eliminating the error you're receiving.

UPDATE #1

Thanks for updating your question to include that information. I understand your reluctance to post your specific info/data here -- you should always feel free to change (i.e, make generic) any data that you don't feel comfortable sharing. The data values usually don't matter in troubleshooting issues like this -- but it is critical to see what properties you're including/setting in the Request and what the Response structure looks like as well.

As described in the table on pages 166-167 of the REST API guide (http://www.docusign.com/sites/default/files/REST_API_Guide_v2.pdf), "You can use either email AND userName OR userId to identify the recipient" in the POST Recipient View request. It looks like your request only specifies userName -- try adding email to the request as well, and that should eliminate the error you're getting.

UPDATE #2

The value you specify for userName in the POST Recipient View request needs to match the value that you specified for the Signer's name in the Create Envelope request -- i.e., this will be the same value that's returned in the name property of the GET Recipients response. Try specifying "Bridget C. Shoemaker" as the value of username in your request (instead of using the value "Third Party Verification"):

"userName":"Bridget C. Shoemaker"

UPDATE #3

Here is where a user can allow or disallow alternate spellings of their name when they're specified as an Envelope recipient (Preferences >> Names Available >> "Senders may add new spellings of my name" (checkbox)):

As you've seen, the "GET Recipients" call will always return the name of each Recipient as they were created in the Envelope -- so you might consider adding a "GET Recipients" call to retrieve the actual Recipient Name prior to making the "POST Recipient View" call -- kind of a hassle, but at least you'd be guaranteed to be able to provide info for the "POST Recipient View" call to succeed.

Cosmopolis

The JSON I posted above does indeed include the userName, email, and clientUserId... I'm not sure if you misread it? I'm specifying the 'email' authenticationMethod as well. And as I've stated multiple times this is not an ongoing issue with our code. ONLY this specific envelope fails to load up the embedded signing URL. All other previous envelopes for this section of our app worked fine, and I can make new envelopes that load up fine as well. – Dam

Sorry about that, I did miss "email" in the JSON you posted. I've updated my answer to add "UPDATE #2". – Cosmopolis

See, that's just it...I am setting the name as 'Third Party Verification' in my initial envelope creation request, and so I'm using that same value when trying to pull back the URL for embedded signing. This goes back to my original hunch...it seems like Docusign altered the value of that user's name when the envelope was created. This is why I asked if Bridget having a docusign account could effect anything (I'm not sure if she does actually, but that's my guess). Again, my code works untouched for someone who does not have her email. Did Docusign alter that name when creating the envelope? – Dam

Maybe you all look up a user by email and then inject their name or something? In my code, even if I was trying to set their name based on user input on my end (which I'm not, I just hard code 'Third Party Verification' for their name), I only got 'Bridget Shoemaker' entered by the investor requesting the verification from her. The middle initial was not captured on my end at all, which is what lead me to wonder about Docusign injecting that name... – Dam

Seems like I recall hearing about a DocuSign user-level setting by which a user can either allow OR disallow alternate spellings of their name (when they're a Recipient of an envelope). Perhaps what's going on here is that "Bridget Shoemaker" has specified DISALLOW for this setting in her DocuSign user account -- therefore, regardless of what name the sender specifies for her, it will always be replaced with "Bridget C. Shoemaker" (the name she's specified in her DocuSign user/membership settings) if the recipient email address matches her email address ([email protected]). – Cosmopolis

Huh... so that ability definitely breaks the API's need to tie those values all together. How as a developer would I know what that user's preferred name would be set to so I could form the request in such a way that this error wouldn't occur? I know I can fix this one manually, but how can I prevent this from happening in the future? – Dam

I've added "UPDATE #3" to my answer. – Cosmopolis

Thanks, I guess I'll just have to do the get recipients call before doing the post recipient view as you suggest. I appreciate the assistance. – Dam

Glad to help. If you wouldn't mind, please mark this as an accepted "Answer", so that others may benefit from this info in the future. – Cosmopolis