Common API Tasks🐈: Require your signers to provide a reason when they decline to sign

Inbar GazitSr. Manager, Developer Content

•

Summary•3 min read

Use the eSignature REST API to make sure signers provide a reason when they decline to sign your envelopes.

Welcome to an splendid new edition of the CAT🐈 (Common API Tasks) blog series. The CAT blogs 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.

In today’s edition I’m going to discuss what happens when your signers decline to sign an envelope that was sent to them. By default, a signer can choose Decline to Sign from the top-right menu, and if they do so, the envelope gets voided without the signer giving any reason.

It may be beneficial to require that your signers (or your customers’ signers) have to provide a reason before they can get the envelope voided when they decline to sign it (similarly to how the sender is required to do so if they wish to void an envelope).

This can be done account-wide for all envelopes that were sent from the account by going to the Signing Settings section of the web admin tool and checking “Require a reason when a recipient declines to sign” and updating the settings for the account.

Requiring signers to provide a reason: setting in the DocuSign UI

Once this is done, the signer will only be able to to decline (and thus void the envelope) after providing a reason in the following dialog:

Of course, like everything else in this blog series, we show you how to do things programmatically, using the Docusign APIs and the Docusign SDKs.

The following code snippets update the account’s settings (For the account that was used to authenticate to Docusign for the purpose of making API calls) and change it to require signers to provide a reason when they decline. Note that this code can only be run if you authenticate as a user with admin privileges.

C#

var docuSignClient = new DocuSignClient(basePath);
// You will need to obtain an access token using your chosen authentication method
docuSignClient.Configuration.DefaultHeader.Add("Authorization", "Bearer " + accessToken);
AccountsApi accountsApi = new AccountsApi(docuSignClient);

AccountSettingsInformation accountSettings = accountsApi.ListSettings(accountId);
accountSettings.RequireDeclineReason = "true";
accountsApi.UpdateSettings(accountId, accountSettings);

Java

Configuration config = new Configuration(new ApiClient(basePath));
// You will need to obtain an access token using your chosen authentication method
config.addDefaultHeader("Authorization", "Bearer " + accessToken);
AccountsApi envelopesApi = new AccountsApi(config);

AccountSettingsInformation accountSettings = accountsApi.listSettings(accountId);
accountSettings.setRequireDeclineReason("true");
accountsApi.updateSettings(accountId, accountSettings);

Node.js

let dsApiClient = new docusign.ApiClient();
dsApiClient.setBasePath(basePath);
// You will need to obtain an access token using your chosen authentication method
dsApiClient.addDefaultHeader('Authorization', 'Bearer ' + accessToken);

let accountsApi = new AccountsApi(dsApiClient);
let accountSettings = accountsApi.listSettings(accountId);
accountSettings.requireDeclineReason = 'true';
accountsApi.updateSettings(accountId, accountSettings);

PHP

$api_client = new \Docusign\eSign\client\ApiClient($base_path);
$config = new \Docusign\eSign\Model\Configuration($api_client);
# You will need to obtain an access token using your chosen authentication method
$config->addDefaultHeader('Authorization', 'Bearer ' + $access_token);
$accounts_api = new \Docusign\eSign\Api\AccountsApi($api_client);

$account_settings = $accounts_api->listSettings($account_id);
$account_settings->setRequireDeclineReason('true');
$accounts_api->updateSettings($account_id, $account_settings);

Python

api_client = ApiClient()
# You will need to obtain an access token using your chosen authentication method
api_client.set_default_header('Authorization', 'Bearer ' + access_token)
accounts_api = AccountsApi(api_client)

account_settings = accounts_api.list_settings(account_id)
account_settings.require_decline_reason = 'true'
accounts_api.update_settings(account_id, account_settings)

Ruby

config = DocuSign_eSign::Configuration.new
config.host = base_path
api_client = DocuSign_eSign::ApiClient.new config
# You will need to obtain an access token using your chosen authentication method
api_client.DefaultHeader['Authorization'] = 'Bearer ' + access_token
accounts_api = DocuSign_eSign::AccountsApi.new api_client

account_settings = accounts_api.list_settings(account_id)
account_settings.require_decline_reason = 'true'
accounts_api.update_settings(account_id, account_settings)

That’s all, folks! I hope you found it useful. 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

Inbar GazitSr. Manager, Developer Content

Inbar Gazit has been with Docusign since 2013 in various engineering roles. Since 2019 he has focused on developer content. Inbar works on code examples including the launchers, available on GitHub in eight languages, and helps build sample apps showcasing the various Docusign APIs. He is also active on StackOverflow, answering your questions. Inbar can be reached at inbar.gazit@docusign.com.