Blog
Home/

Common API Tasks🐈: Adding users to your Docusign account

Inbar Gazit
Inbar GazitSr. Manager, Developer Content
•
Summary•4 min read

Step by step review on how to programmatically add new users to your Docusign account

    • C#
    • Java
    • Node.js
    • PHP
    • Python
    • Ruby

    Table of contents

    Common API Tasks

    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.

    Organization, accounts, members and users

    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

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

    More posts from this author

    Related posts

    • Common API Tasks

      Common API Tasks🐈: List all your Maestro workflows using the Maestro API

      Inbar Gazit
      Inbar Gazit
    • Common API Tasks🐈: Find a web form by name

      Inbar Gazit
      Inbar Gazit

    Common API Tasks🐈: Find a web form by name

    Inbar Gazit
    Inbar Gazit

    Discover what's new with Docusign IAM or start with eSignature for free

    Explore Docusign IAMTry eSignature for Free
    Person smiling while presenting