如何使用REST API为DocuSign中的收件人设置clientUserId？

Question

I'm trying to create a RecipientView to send through an app to the recipients of envelopes that are created. With DocuSign's newer API, this requires a userName which is entered by the person who creates the document needed to be signed, an email which is just the email of the recipient, and a clientUserId which is a sender generated string value that authenticates the recipient as an embedded signer so that a RecipientView can be generated to host the signing ceremony.

DocuSign documentation references that I need to set clientUserId, but it doesn't mention how to to do this other than when the envelope is created through the API. However, in this scenario, envelopes will be created by DocuSign Admin clients through the templates on the actual web interface, and not through the API.

My code to generate the RecipientView is all set up here:

$url = "https://demo.docusign.net/restapi/v2/accounts/$account_id/envelopes/$envelope_id/views/recipient";

$body = array("returnUrl" => "http://www.docusign.com/devcenter",
              "authenticationMethod" => "None",
              "email" => "$email",
              "userName" => "$name",
              "recipientId" => "$recipientId",
              "clientUserId" => "1000"
);

$body_string = json_encode($body);

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    'Accept: application/json',
    'Content-Type: application/json',
    'Content-Length: '.strlen($body_string),
    "Authorization: Bearer $access_token"
));
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $body_string);
$json_response = curl_exec($curl);

$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);

if ($status != 201){
    die('Could not connect to end point: '.mysqli_error($conn));
}

$response = json_decode($json_response, true);
$url = $response["url"];

This code does work when the embedded signer is the Admin account, but not when the envelope is sent to an actual recipient. The return JSON from DocuSign after this request should be:

{
    "url": "example.example.com"
}

However, the return I get for recipients that are not the Admin of the DocuSign account is:

{
    "errorCode": "UNKNOWN_ENVELOPE_RECIPIENT",
    "message": "The recipient you have identified is not a valid recipient of the 
               specified envelope."
}

I believe not setting clientUserId is the reason behind this, since the documentation says I need to set clientUserId and not just create a value when making the call. How do I set a recipient's clientUserId via the REST API?

UPDATE: Within this scenario, I will not be the one creating and sending envelopes. That will be done by the clients I have through my app, and the large majority of them will most likely use the web interface to do this, not the API. I do have access to all information regarding the Admin account for each client, including the Integrator Key, Access Tokens, Envelope IDs, Account IDs, etc.

Answer 1

For Embedded Signing (aka Recipient View) there are two calls you need to make. Well actually 3 calls including the initial Login API but it sounds like you've got that working so I'll focus on the other two.

Step #1: Create an envelope with an embedded recipient. When adding the recipient make sure you set their name, email, recipientId, and clientUserId.

Step #2: Request the Recipient View of the envelope for your signer. To do so you need to call the EnvelopeViews: createRecipient API and you must reference the same exact set of values for the recipient that you set in step 1 (i.e. name, email, recipientId, and clientUserId)

Check out the Signing from Within your App API Recipe for a full code sample.