From the Trenches: User management in eSignature vs. DocuSign Admin API
If you’ve ever used a third-party or partner integration like Salesforce, chances are you’re already aware that some special user permissions or other provisioning steps can be required in order to make the integration fully functional. What you may not be aware of is that you can also manipulate a number of these settings through our eSignature and DocuSign Admin APIs.
While there are other account-level settings that can be flagged with these types of API calls, for the purposes of this blog I’m going to focus on user management and what can actually be managed. If you’ve ever seen an error message related to a sender being unable to set a recipient email language, “user does not have access to templates / powerforms, etc…”, these calls can be used to address those problems without needing to reach out to Customer Support.
Let’s start on the eSign side:
The endpoint to manipulate user settings is accountId/users/UserId/settings. The first thing you’ll notice when checking the response to a GET request at this URI are a set of three arrays: userSettings, signerEmailNotifications, and senderEmailNotifications. Yes, you read that correctly: if you are an administrator, this endpoint allows you to alter the email notification settings for members of your account.
One key thing to note is that you’re only going to have access to these settings for users that are a part of your account. What I mean by that is that you cannot manipulate a recipient’s notification settings unless they are a member of your account.
Example:
"signerEmailNotifications": {
"envelopeActivation": "true",
"envelopeComplete": "true",
"carbonCopyNotification": "true",
"certifiedDeliveryNotification": "true",
"envelopeDeclined": "true",
"envelopeVoided": "true",
"envelopeCorrected": "true",
"reassignedSigner": "true",
"purgeDocuments": "true",
"faxReceived": "true",
"documentMarkupActivation": "true",
"agentNotification": "true",
"offlineSigningFailed": "true",
"whenSigningGroupMember": "true",
"commentsReceiveAll": "false",
"commentsOnlyPrivateAndMention": "true"
},
"senderEmailNotifications": {
"envelopeComplete": "true",
"changedSigner": "true",
"senderEnvelopeDeclined": "true",
"withdrawnConsent": "true",
"recipientViewed": "true",
"deliveryFailed": "true",
"offlineSigningFailed": "true",
"commentsReceiveAll": "false",
"commentsOnlyPrivateAndMention": "true",
"powerformResponsesLimitNotificationEmail": "true",
"clickwrapResponsesLimitNotificationEmail": "true"
}
As you can see, the flags to enable or disable these settings for this specific user are straightforward true/false flags. As a general rule, you should really only make alterations like these during the provisioning process, as users may react very strongly when they learn that someone turned one of these flags off and they missed an important contract for which they were expecting an email.
Now, let’s get to the fun part: userSettings.
Since DocuSign retired the Classic DocuSign Experience, the primary method of controlling user permissions has been through permission profiles. However, DocuSign Support does have a backend system that allows us to change individual user flags when the situation is authorized or called for. With this endpoint, you can do the same!
When looking over the data listed in the userSettings array, you’ll notice that this endpoint references some of the older DocuSign technologies that have been deprecated or taken offline completely. The flags for these older settings will not honor changes that you attempt to make; however, some of the more useful ones can. These flags include items like access to templates, PowerForms, Bulk Send, Other Actions/Document Upload, and Comments; a number of other flags can be handled by your system automatically when they create the user.
Sounds great! What about the Admin API side of things?
While the Admin API does not give this granular control, it does have some additional options that the regular eSignature side of things does not have.
The Admin API not only allows you to create users via an API call, but it also allows you to silently activate them. This feature is only available for accounts with a claimed domain, and only is applicable to users that are being created using that claimed domain for their email address.
This endpoint allows you to manually activate a user seat should you run into issues with email notifications or silent activation.
Activation for CLM + eSignature users
This call allows you to create a CLM and eSignature user with one call, while potentially also silently activating it.
Updating a User’s Email Address
This is a bigger one: for a large number of potential reasons, you may find yourself in a situation where you need to update a user’s email address, but they are not able to access a machine, inbox, or DocuSign account. As you can do in the web UI, you can use the DocuSign Admin API to update a user’s email address behind the scenes.
There are some other handy elements to this API, but for sake of the scope of this post, I’ll stick with user management. The DocuSign Admin API has a number of feature advantages, while the eSignature side has a larger degree of control over specific user flags. If you can’t decide if you want to use one path or the other, keep in mind that you can do both. Just keep an eye on your OAuth scopes and make sure the token you’re using references scopes to both the eSignature and Admin AP. For a full list see Authentication scopes on our Developer Center.
