Common API Tasks🐈: Adding a recipient to an in-flight envelope

If you’re like me, before you send an email, or a text message, or an envelope, you double-check it and make sure that it's all correct. Your customers using your integrations to send envelopes probably do that as well. But, alas, sometimes mistakes happen and we forget to add that new hire in accounting; she needs to get a copy of the expense report at the end. Sounds familiar? The envelope has already been sent, and now you need to add another recipient. It’s even possible someone already signed it (but not everyone, it’s not complete yet). You can add a recipient programmatically using the eSignature REST API, and that’s what I’m going to show you in this blog post. 

This post is part of a series I call Common API Tasks (CAT) and is meant to help you with small, specific, SDK-supported tasks. That means I always give you six code examples in our primary coding languages: C#, Java, Node.js, PHP, Python, and Ruby. No developer is left behind (well, unless you’re a COBOL developer; then you’re out of luck :).

So, let’s get to business. We have an envelope that has been sent. You have to know the envelopeId, which is a GUID that uniquely identifies an envelope in the DocuSign system. Each envelope in DocuSign also has a specific status. The envelope in this case is in sent status. That means that the recipients can start signing it. It’s possible, for example, that the envelope was sent to two recipients, both of whom received an email (or signed using embedded signing), but one of them has not signed yet. It's important that at least one recipient has yet to act on the envelope. That is because, if all recipients acted on the envelope, then it automatically becomes complete. A complete envelope is done, finished, and cannot be modified. So we have to ensure our envelope is not complete. 

So, we have an envelope that was sent for two recipients to sign. We would like to add Jane Doe as a Carbon Copy recipient, and ensure she only gets her copy when both signers finish signing. We use the UpdateRecipients method of the SDK. This method can be used to modify existing recipients as well, but in our case, we just want to add a new one. 

C#

var apiClient = new ApiClient(basePath);
// You will need to obtain an access token using your chosen authentication flow
apiClient.Configuration.DefaultHeader.Add("Authorization", "Bearer " + accessToken);
var envelopesApi = new EnvelopesApi(apiClient);
string envelopeId = "2a4fe901-xxxx-xxxx-xxxx-0844734eb7a0";
var recipients = new Recipients { CarbonCopies = new List<CarbonCopy>() };
recipients.CarbonCopies.Add(new CarbonCopy 
{ 
    Email = "janedoe@example.com", 
    Name = "Jane Doe", 
    DeliveryMethod = "email", 
   RecipientId = "11", // This has to be different only for this envelope; GUIDs are OK, too
   RoutingOrder = "3"  // We already had two recipients; Jane will get the copy after they have both signed
});
// When making the API call, we get back a summary of what was updated. If there are errors, no exception will be thrown; instead, the summary will include the error information
var summary = envelopesApi.UpdateRecipients(accountId, envelopeId, recipients);

Java

// You will need to obtain an access token using your chosen authentication flow 
Configuration config = new Configuration(new ApiClient(basePath));
config.addDefaultHeader("Authorization", "Bearer " + accessToken);
EnvelopesApi envelopesApi = new EnvelopesApi(config);
String envelopeId = "2a4fe901-xxxx-xxxx-xxxx-0844734eb7a0";
Recipients recipients = new Recipients();
recipients.setCarbonCopies(new java.util.List<CarbonCopy>());
CarbonCopy cc = new CarbonCopy();
cc.setEmail("janedoe@example.com",);
cc.setName("Jane Doe");
cc.setDelieveryMethod("email");
cc.setRecipientId("11"); // This has to be different only for this envelope; GUIDs are OK, too
cc.setRoutingOrder("3") // We already had two recipients; Jane will get the copy after they have both signed
recipients.getCarbonCopies().Add(cc);
// When making the API call, we get back a summary of what was updated. If there are errors, no exception will be thrown; instead, the summary will include the error information
RecipientsUpdateSummary summary = envelopesApi.UpdateRecipients(accountId, envelopeId, recipients);

Node.js

// You will need to obtain an access token using your chosen authentication flow 
let dsApiClient = new docusign.ApiClient();
dsApiClient.setBasePath(basePath);
dsApiClient.addDefaultHeader('Authorization', 'Bearer ' + accessToken);
let envelopesApi = new docusign.EnvelopesApi(dsApiClient);
let recipients = new docusign.Recipients { CarbonCopies = []};
recipients.carbonCopies.push(new docusign.CarbonCopy 
{ 
    Email = 'janedoe@example.com', 
    Name = 'Jane Doe', 
    DeliveryMethod = 'email', 
   RecipientId = '11', // This has to be different only for this envelope; GUIDs are OK, too
   RoutingOrder = '3'  // We already had two recipients; Jane will get the copy after they have both signed
});
// When making the API call, we get back a summary of what was updated. If there are errors, no exception will be thrown; instead. the summary will include the error information
let summary = envelopesApi.updateRecipients(accountId, envelopeId, {recipients});

PHP

# You will need to obtain an access token using your chosen authentication flow 
$api_client = new \DocuSign\eSign\client\ApiClient($base_path);
$config = new \DocuSign\eSign\Model\Configuration($api_client);
$config->addDefaultHeader('Authorization', 'Bearer ' + $access_token);
$envelopes_api = new \DocuSign\Api\EnvelopesApi($config);
$envelope_id = '2a4fe901-xxxx-xxxx-xxxx-0844734eb7a0';
$recipients = new \DocuSign\eSign\Model\Recipients();
$recipients->setCarbonCopies([]);
$cc = new \DocuSign\eSign\Model\CarbonCopy();
$cc->setEmail(‘janedoe@example.com’);
$cc->setName = (‘Jane Doe’); 
$cc->setDeliveryMethod(‘email’); 
$cc->setRecipientId(‘11’); # This has to be different only for this envelope; GUIDs are OK, too
$cc->setRoutingOrder(‘3’);  # We already had two recipients; Jane will get the copy after they have both signed
array_push($recipients->getCarbonCopies(), $cc);
# When making the API call, we get back a summary of what was updated. If there are errors, no exception will be thrown; instead, the summary will include the error information
$summary = $envelopes_api->updateRecipients($account_id, $envelope_id, $recipients);

Python

# You will need to obtain an access token using your chosen authentication flow 
api_client = ApiClient()
api_client.set_default_header('Authorization', 'Bearer ' + access_token)
envelopes_api = EnvelopesApi(config)
envelope_id = '2a4fe901-xxxx-xxxx-xxxx-0844734eb7a0'
recipients = Recipients()
recipients.carbon_copies = []
cc = CarbonCopy()
cc.email = 'janedoe@example.com'
cc.name = 'Jane Doe'
cc.delivery_method ='email'
cc.recipient_id = '11' # This has to be different only for this envelope; GUIDs are OK, too
cc.routing_order = '3'  # We already had two recipients; Jane will get the copy after they the both signed
recipients.carbon_copies.append(cc)
# When making the API call, we get back a summary of what was updated. If there are errors, no exception will be thrown; instead, the summary will include the error information
summary = envelopes_api.update_recipients(account_id, envelope_id, recipients)

Ruby

# You will need to obtain an access token using your chosen authentication flow 
config = DocuSign_eSign::Configuration.new
config.host = base_path
api_client = DocuSign_eSign::ApiClient.new config
api_client.DefaultHeader['Authorization'] = 'Bearer ' + access_token
envelopes_api = DocuSign_eSign::EnvelopesApi.new api_client
envelope_id = '2a4fe901-xxxx-xxxx-xxxx-0844734eb7a0'
recipients = DocuSign_eSign::Recipients.new
recipients.carbon_copies = []
cc = DocuSign_eSign::CarbonCopy.new
cc.email = 'janedoe@example.com'
cc.name = 'Jane Doe'
cc.delivery_method ='email'
cc.recipient_id = '11' # This has to be different only for this envelope; GUIDs are OK, too
cc.routing_order = '3'  # We already had two recipients; Jane will get the copy after they have both signed
recipients.carbon_copies.push(cc)
# When making the API call, we get back a summary of what was updated. If there are errors,- no exception will be thrown; instead, the summary will include the error information.
summary = envelopes_api.update_recipients(account_id, envelope_id, recipients)

I hope you found this useful. As usual, if you have any questions, comments, or suggestions for topics to feature in future Common API Tasks posts, feel free to email me. Until next time…

Additional resources

• DocuSign Developer Center
• @DocuSignAPI on Twitter
• DocuSign for Developers on LinkedIn
• DocuSign for Developers on YouTube
• DocuSign Developer Newsletter