INVALID_USERID error code when trying to retrieve recipient view using REST API

Question

I am trying to retrieve the recipient view for an envelope using the REST API, and I am getting the INVALID_USERID error code in my response.

Request:

POST https://demo.docusign.net/restapi/v2/accounts/<redacted>/envelopes/<redacted>/views/recipient HTTP/1.1
Authorization: bearer <redacted>
Content-Type: application/json
Host: demo.docusign.net
Content-Length: 124
Expect: 100-continue

{"authenticationMethod":"userId","clientUserId":"2","returnUrl":"<redacted>","userId":"1"}

Response:

HTTP/1.1 400 Bad Request
Cache-Control: no-cache
Content-Length: 70
Content-Type: application/json; charset=utf-8
Date: Fri, 11 Apr 2014 13:48:42 GMT
Strict-Transport-Security: max-age=7776000; includeSubDomains

{
  "errorCode": "INVALID_USERID",
  "message": "Invalid UserId."
}

As you can see, I am trying to authenticate the recipient view request using the option to provide the clientUserId and userId (since they are an embedded signer) sent in original POST to create the envelope as opposed to using the email/username method. The API documentation does not indicate what authenticationMethod value to use to indicate that I am doing this; it only lists that "email" should be used for the email/username method. Therefore, I'm making my best guess and using "userId" for that value.

I have verified that the clientUserId and userId (recipientId from the envelope request) match what I'm sending in here.

Envelope Request:

POST https://demo.docusign.net/restapi/v2/accounts/<redacted>/envelopes HTTP/1.1
Authorization: bearer <redacted>
Content-Type: multipart/form-data; boundary="AAA"
Host: demo.docusign.net
Content-Length: 309312
Expect: 100-continue
Connection: Keep-Alive

--AAA
Content-Type: application/json; charset=utf-8
Content-Disposition: form-data

{"documents":[{"name":"EOS.pdf","documentId":"1","order":1}],"emailBlurb":null,"emailSubject":"Subject","recipients":{"signers":[{**"clientUserId":"2"**,"email":"asdf@asdf.com",**"recipientId":"1"**,"Name":"John Doe","Tabs":{"signHereTabs":[{"anchorString":"Anchor","anchorIgnoreIfNotPresent":true,"anchorUnits":null,"anchorXOffset":-10,"anchorYOffset":-15}]}}]},"status":"sent"}
--AAA
Content-Type: application/pdf
Content-Disposition: file; filename=EOS.pdf; documentid=1

<snip>

--AAA--

Is there anything I need to do to the request to get it to submit correctly?

Answer 1

Based on the "Create Envelope" request that you posted, the valid "POST Recipient View" request body (to retrieve the URL to launch the recipient's DocuSign signing session) would be:

{
    "authenticationMethod": "Email",
    "clientUserId": "2", 
    "userName": "John Doe",
    "email": "asdf@asdf.com"
    "returnUrl": "<redacted>",
}

In other words, you need to make the following changes to the "POST Recipient View" request body that you posted in your question:

1. set authenticationMethod = Email
2. remove the userId property
3. add the email property
4. add the userName property

Specifying an authenticationMethod of "Email" simply means that no advanced form of recipient authentication is required (i.e., you're not using ID Check, Phone Authentication, Access Code, etc., etc., etc.).

--- UPDATE (in response to first comment) ---

If you're not using any advanced form of recipient authentication (as your "Create Envelope" request shows you're not) then the authenticationMethod needs to be set to "Email". This is true whether you use userId to identify the recipient, or a combination of email and userName to identify the recipient.

I've never personally tried using userId in the POST Recipient View request to identify the recipient (I've always used email and userName), but according to the documentation it should be valid to specify userId in the POST Recipient View request (and not email or userName). However, if you insist on using userId in the POST Recipient View request to identify the recipient, then you need to set it to the correct value. i.e., (from the documentation):

If userId is used and a clientUserId is provided, the userId must match a recipientId (which can be retrieved with a GET recipients call) for the envelope. 

The important thing to realize here is that the value of userId in the POST Recipient View request is NOT the same as the value of recipientId in your Create Envelope request. Instead, the value of userId will be a GUID -- one that you can only retrieve by issuing a GET Recipients request. i.e.,

GET https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes/{{envelopeId}}/recipients?include_tabs=false

This request will return a collection of recipients -- according to the documentation, it's the recipientId property value that you'll need to specify in your POST Recipient View request (as "userId"). For example, here's a GET Recipients response for one of my envelopes:

{
    "signers": [
        {
            "name": "Bob Adams",
            "email": "bobsemail@outlook.com",
            "recipientId": "d1b33cf7-d630-4fcb-a7fb-ff6f3d946d81",
            "recipientIdGuid": "d1b33cf7-d630-4fcb-a7fb-ff6f3d946d81",
            "requireIdLookup": "false",
            "userId": "46d0615d-0ed2-4def-9918-9dc14fa82f70",
            "routingOrder": "1",
            "status": "sent"
        }
    ],
    "agents": [],
    "editors": [],
    "intermediaries": [],
    "carbonCopies": [],
    "certifiedDeliveries": [],
    "inPersonSigners": [],
    "recipientCount": "1"
}

BTW -- if using the value of recipientId from the GET Recipients response as the value of userId in the POST Recipient View request doesn't work (even though the documentation says it should), then I'd probably instead try using the value of userId from the GET Recipients response as the value of userId in the POST Recipient View request.