Common API Tasks🐈: Adding users to your DocuSign account

Welcome to another post of the Common API Tasks blog series for developers! This blog series is focused on simple, yet useful pieces of functionality that can be accomplished using one of the DocuSign APIs. In past posts I helped you with things like how to void an envelope or how to retrieve tab data. In my last post, I addressed an imminent issue for many of you: how to use DocuSign eNotary functionality with the DocuSign eSignature REST API. In this post I’m going to tackle a rather mundane task: adding new users to your DocuSign account (or to any account really).

First, let’s review some basic concepts:  organizations, accounts, users and memberships.

In the hierarchy of objects in the DocuSign system, the organization is at the top. An organization can have one or more accounts. Think of it as a large enterprise company that may have different accounts for different divisions or departments.

The account level is the most important for our discussion. An account is a single unit in which you work when using DocuSign. Every API call you make to the eSignature REST API is made in the context of a specific account that is the baseURI of your API endpoint. An account can have one or more users. A user is typically associated with an individual person and has an email address and a name. When you log into DocuSign your credentials must match to a user in the system. However, to make matters a bit more interesting, a user can be a member of more than one account. That’s where we start talking about members. A member is a combination of a user and account. If you only have a single user using a single account, the member is still there, but it’s trivial. However, if you are a member of two or more accounts, you must also choose which membership, or which account, you use.

When you add a user to your account, that user may already be a member of another account. In this case, you are not actually creating a new user in the DocuSign system, you’re only creating a new membership for this existing user in your account. If this individual does not yet have a user in DocuSign, then a new user and a new member are created. DocuSign determines the uniqueness of a user based on the combination of an email address and full name. If there’s even a small difference between them (i.e. “Michael A. Person” vs. “Michael Person”) it would be a different user.

When a new user is added to an account, the individual will receive an activation email. If they already have a DocuSign user, they will have to authenticate with that user’s password. If they don’t have a user in any DocuSign account, they would have to create one by typing a new password.

With me so far? Now let’s get to some coding.

The following code snippets add Linda and Sam as new users of your account. Each of them will receive an activation email that also requires them to enter an activation code before they can proceed. This part is optional, but is a good idea to enhance the security of your code. There’s a lot more information that can be provided about users at the time when they are created. It is not recommended to provide a user's password, but you can do so as well (in which case they’ll still get an activation email, but won’t have to set their password).

C#

// You will need to obtain an accessToken using your chosen authentication flow 
var apiClient = new ApiClient(basePath);
apiClient.Configuration.DefaultHeader.Add("Authorization", "Bearer " + accessToken);
var usersApi = new UsersApi(apiClient);
var newUsersDefinition = new NewUsersDefinition { NewUsers = new List<UserInformation>()};
UserInformation user1 = new UserInformation { Email = "linda@example.com", UserName = "Linda One", Company = "ABC", ActivationAccessCode = "123456" };
UserInformation user2 = new UserInformation { Email = "sam@example.com", UserName = "Sam Two", Company = "XYZ", ActivationAccessCode = "123456" };
newUsersDefinition.NewUsers.Add(user1);
newUsersDefinition.NewUsers.Add(user2);
NewUsersSummary newUsersSummary = usersApi.Create(accountId, newUsersDefinition);

Java

// You will need to obtain an accessToken using your chosen authentication flow 
Configuration config = new Configuration(new ApiClient(basePath));
config.addDefaultHeader("Authorization", "Bearer " + accessToken);
UsersApi usersApi = new UsersApi(config); 
NewUsersDefinition newUsersDefinition = new NewUsersDefinition();
newUsersDefinition.setNewUsers(new java.util.List<UserInformation>());
UserInformation user1 = new UserInformation();
user1.setEmail("linda@example.com");
user1.setUserName("Linda One");
user1.setCompany("ABC");
user1.setActivationAccessCode("123456");
UserInformation user2 = new UserInformation();
user2.setEmail("sam@example.com");
user2.setUserName("Sam Two");
user2.setCompany("XYZ");
user2.setActivationAccessCode("123456");
newUsersDefinition.NewUsers.Add(user1);
newUsersDefinition.NewUsers.Add(user2);
NewUsersSummary newUsersSummary = usersApi.create(accountId, newUsersDefinition);

Node.js

// You will need to obtain an accessToken using your chosen authentication flow 
let dsApiClient = new docusign.ApiClient();
dsApiClient.setBasePath(basePath);
dsApiClient.addDefaultHeader('Authorization', 'Bearer ' + accessToken);
let usersApi = new docusign.UsersApi(dsApiClient);
let user1 = docusign.userInformation.consturctFromObject({
    email: 'linda@example.com',
    userName: 'Linda One',
    company: 'ABC',
    activationAccessCode: '123456')};
let user2 = docusign.userInformation.consturctFromObject({
    email: 'sam@example.com',
    userName: 'Sam Two',
    company: 'XYZ',
    activationAccessCode: '123456')};
let newUsersDefinition = docusign.newUsersDefinition.constructFromObject({
    newUsers: [user1, user2])};
let newUsersSummary = usersApi.create(accountId, newUsersDefinition);

PHP

# You will need to obtain an accessToken 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);
$users_api = new \DocuSign\Api\UsersApi($config);
$user1 = new \DocuSign\eSign\Model\UserInformation();
$user1->setEmail('linda@example.com');
$user1->setUserName('Linda One');
$user1->setCompany('ABC');
$user1->setActivationAccessCode('123456');
$user2 = new \DocuSign\eSign\Model\UserInformation();
$user2->setEmail('sam@example.com');
$user2->setUserName('Sam Two');
$user2->setCompany('XYZ');
$user2->setActivationAccessCode('123456');
$new_users_definition = new \DocuSign\eSign\Model\NewUsersDefinition();
$new_users_definition->setNewUsers([$user1, $user2]);
$users_api->create($new_users_definition);

Python

# You will need to obtain an accessToken using your chosen authentication flow 
api_client = ApiClient()
api_client.set_default_header('Authorization', 'Bearer ' + access_token)
users_api = UsersApi(api_client)
user1 = UserInformation()
User1.email = 'linda@example.com'
user1.user_name = 'Linda One'
User1.company = 'ABC'
user1.activation_access_code = '123456'
user2 = UserInformation()
User2.email = 'sam@example.com'
user2.user_name = 'Sam Two'
User2.company = 'XYZ'
user2.activation_access_code = '123456'
new_users_definition = new NewUsersDefinition()
new_users_definition.newUsers = []
new_users_definition.newUsers.append(user1)
new_users_definition.newUsers.append(user2)
new_users_summary = usersApi.create(accountId, new_users_definition)

Ruby

# You will need to obtain an accessToken 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
users_api = DocuSign_eSign::UsersApi.new api_client
user1 = DocuSign.eSign::UserInformation.new
user1.email = 'linda@example.com'
user1.user_name = 'Linda One'
user1.company = 'ABC'
user1.activation_access_code = '123456'
user2 = DocuSign.eSign::UserInformation.new
user2.email = 'sam@example.com'
user2.user_name = 'Sam Two'
user2.company = 'XYZ'
user2.activation_access_code = '123456'
new_users_definition = DocuSign.eSign::NewUsersDefinition.new
new_users_definition.new_users = []
new_users_definition.new_users.push(user1)
new_users_definition.new_users.push(user2)
new_users_summary = usersApi.create(accountId, new_users_definition)

After you successfully run this code, the object you get back will include a list of all the new users that got created, including their userIDs (in GUID format). This method does not error out, but rather will give you an error for each specific user if that user’s information is invalid. This way, if you are trying to add a few users and one of them has an error, the rest will still be added successfully.

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

• Manage Users in the DocuSign Admin guide
• DocuSign Developer Center
• @DocuSignAPI on Twitter
• DocuSign for Developers on LinkedIn
• DocuSign for Developers on YouTube
• DocuSign Developer Newsletter