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...
