Common API Tasks🐈: Requesting a signature from a signing group

Welcome to another edition of the CAT (Common API Tasks) blog. This blog series is all about giving you useful information about using the Docusign APIs. In each post I provide all you need to complete small, specific, SDK-supported tasks using one of our APIs.

You can find all articles in this series on the Docusign developer blog.

A year ago I wrote a post about how to use the eSignature REST API to create a signing group. Signing groups enable you to send an envelope to a predefined group of recipients and have any one member of the group open it and sign it with their own signature. So, one of the developers who read my article sent me an email asking how to take the next obvious step: use the signing group that he just created in an envelope as one of the recipients. I’m very happy to know my articles are useful and so I’m also glad to write one per request. Let’s see how to do that.

To send an envelope to the signing group as one of the recipients, you must know the signing group identifier. The signingGroupId is not a GUID like many other such identifiers. Instead, this is a short number that may not be unique across the Docusign platform, but is unique for your own Docusign account. There are two ways you can find the signingGroupId; see below.

Finding the signingGroupId programmatically

If you followed my previous blog post on this topic, the last line of code snippet (in all six languages) returned an object (which I ignored in the code snippets provided in that post). This object has information about the signing groups that were just created. Here is how you can extract the signingGroupId, assuming your application has previously created a new signing group:

C#

SigningGroupInformation signingGroupInformation = signingGroupsApi.CreateList(accountId, signingGroupInfo);
string signingGroupId = signingGroupInformation.Groups[0].SigningGroupId;

Java

SigningGroupInformation signingGroupInformation = signingGroupsApi.createList(accountId, signingGroupInfo);
String signingGroupId = signingGroupInformation.getGroups()[0].getSigningGroupId();

Node.js

var signingGroupInformation = signingGroupsApi.createList(accountId, signingGroupInfo);
var signingGroupId= signingGroupInformation.groups[0].signingGroupId;

PHP

$signing_group_information = $signing_groups_api.createList($account_id, $signing_group_info);
$signing_group_id = $signing_group_information->getGroups[0]->getSigningGroupId();

Python

signing_group_information = signing_groups_api.createList(account_id, signing_group_info)
signing_group_id = signing_group_information.groups[0].signing_group_id

Ruby

signing_group_information = signing_groups_api.createList(account_id, signing_group_info)
signing_group_id = signing_group_information.groups[0].signing_group_id

Finding the signingGroupId using the web app

To find the signingGroupId in the web app is very simple as well. Go to the Settings tab of your account and select Signing Groups from the left menu. Pick the group you want to use and select it. The Edit Signing Group pop-up window will appear, showing information about the signing group including the Signing Group ID read-only field.

How to programmatically set the recipient to use a signing group

Now that you have your signingGroupId handy, you’re ready to send an envelope to the signing group. The following code snippets show you only how to set a recipient to use a signing group. You will still need to add documents and tabs, which are unaffected by using a signing group. 

One thing to keep in mind: you cannot use embedded signing with a signing group. This means that if you try to provide a clientUserId, you’ll receive an error message.

When you add a signing group to your envelope, all members of the group will receive the email (when it’s their time based on the routing order) to sign at the same time. Only one of them has to sign the envelope for it to proceed. 

C#

// signingGroupId should hold the string with the Signing Group ID
Signer signer1 = new Signer 
{
    Name = "test1", // Signing group name
    SigningGroupId = signingGroupId,
    RecipientId = "1",
};

Java

// signingGroupId should hold the string with the Signing Group ID
Signer signer = new Signer();
    signer.setName("test1"); // Signing group name
    signer.setSigningGroupId(signingGroupId);
    signer.setRecipientId("1");

Node.js

// signingGroupId should hold the string with the Signing Group ID   
let signer1 =  docusign.Signer.constructFromObject({
    name: 'test1', // Signing group name
    signingGroupId: signingGroupId,
    recipientId: '1'});

PHP

# $signing_group_id should hold the string with the Signing Group ID   
$signer1 = new Docusign\eSign\Model\Signer([
    'name' => 'test1', # Signing group name
    'signing_group_id' => $signing_group_id,
    'recipient_id' => '1']);

Python

signer1 = Signer(
  name='test1', # Signing group name
  signing_group_id=signing_group_id,
  recipient_id='1',
)

Ruby

# signing_group_id should hold the string with the Signing Group ID   
signer1 = DocuSign_eSign::Signer.new
signer1.name = 'test1' # Signing group name
signer1.signing_group_id = signing_group_id
signer1.recipient_id = '1'

I hope you found this useful. As usual, if you have any questions, comments, or suggestions for topics for 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