How to add users via bulk import

This topic demonstrates how to bulk import users and add user data from an example CSV (comma-separated value) file into a Docusign Admin organization.

Required data

Running the code in this how-to requires this data:

Step 1. Obtain your OAuth token

To make the API calls shown in this how-to, you need a valid OAuth access token. Docusign supports access tokens for three different recommended OAuth grant types: Public Authorization Code Grant, Confidential Authorization Code Grant, and JSON Web Token (JWT) Grant. Choose the OAuth grant type appropriate for your scenario.

Docusign Admin OAuth access tokens are the same ones used for our eSignature REST API, although you must request one or more Docusign Admin scopes to call the Docusign Admin API. The endpoint calls made in this how-to require that you request the Docusign Admin-specific user_write scope when obtaining your access token.

Step 2. Construct your API headers

After you have a valid OAuth access token, you are ready to construct the API headers that you will pass to the API call. Construct your headers like this, but make sure to substitute your valid OAuth access token for {ACCESS_TOKEN}.

declare -a Headers=('--header' "Authorization: Bearer ${ACCESS_TOKEN}"
   '--header' "Accept: application/json"
   '--header' "Content-Type: application/json")

Step 3. Create the bulk import request

To import the user data from a CSV file, call UserImport:addBulkUserImport to create a new bulk import add users request. When complete, the users whose data is contained in this CSV file will be added to the specified account in your organization.

Rather than specifying a file to use for the request, the CSV data is defined within the request body, as demonstrated in this how-to.

Note: When adding user data, the AccountId, UserName, FirstName, LastName, UserEmail, and PermissionSet fields are required. For updating user data, APIUsername is required to identify the user, rather than UserName/FirstName/LastName, and PermissionSet is not required.

request_data=$(mktemp /tmp/request-oa.XXXXXX)
printf \
    'AccountID,UserName,UserEmail,PermissionSet
\"'${API_ACCOUNT_ID}'\",FirstLast1,exampleuser1@example.com,DS Viewer,
\"'${API_ACCOUNT_ID}'\",FirstLast2,exampleuser2@example.com,DS Viewer
' >>$request_data
# Create a temporary file to store the response
response=$(mktemp /tmp/response-oa.XXXXXX)
curl --request POST ${base_path}/v2/organizations/${ORGANIZATION_ID}/imports/bulk_users/add \
    "${Headers[@]}" \
    --data-binary @${request_data} \
    --output ${response}
echo ''
echo 'Response:'
echo ''
cat $response
echo ''

Expected response

You should see a JSON response similar to this.

The important parts of the Sample response are highlighted in the table below.

{
   id: "cd400bc0-xxxx-xxxx-xxxx-c79a7c93416f",
   type: "add_users",
   requestor: {
      name: "Susan Signer",
      id: "c316f86c-xxxx-xxxx-xxxx-6b39358381d2",
      type: "user",
      email: "test@email.com"
   },
   created: "2022-12-14T19:25:41.660Z",
   last_modified: "2022-12-14T19:25:41.660Z",
   status: "queued",
   has_csv_results: false
}

If you receive a 401 - Unauthorized response, your access token is not valid for the endpoint. If you receive this error:

• Make sure that your access token has user_read and user_write scopes.
• Make sure that the calling user has admin rights.

Creating and provisioning the bulk import list can take some time, especially for large organizations spread out over several regions. You can check the status of your bulk import request by calling UserImport:getBulkUserImportRequest as demonstrated in Step 4.

Step 4. Check the request status

It can take some time for the response to a bulk user import request to be fully created, depending on the number of users that it contains and the regions it encompasses. You can call UserImport:getBulkUserImportRequest to check the status of your pending request and, if complete, obtain a URL that you can call to download the CSV file containing the data to verify that the updates were made.

Important: Be sure to set the importId value in the path with the import ID of the bulk user export request that you retrieved in the previous step.

curl --request GET ${base_path}/v2/organizations/${ORGANIZATION_ID}/imports/bulk_users/${importId} \
    "${Headers[@]}" \
    --output ${response}

Expected response

You should see a JSON response similar to this.

{
   id: "cd400bc0-xxxx-xxxx-xxxx-c79a7c93416f",
   type: "add_users",
   requestor: {
      name: "Susan Signer",
      id: "c316f86c-xxxx-xxxx-xxxx-6b39358381d2",
      type: "user",
      email: "test@email.com"
   },
   created: "2022-12-14T19:25:41.660Z",
   last_modified: "2022-12-14T19:27:02.169Z",
   status: "completed",
   user_count: 2,
   processed_user_count: 2,
   added_user_count: 0,
   updated_user_count: 2,
   closed_user_count: 0,
   no_action_required_user_count: 0,
   error_count: 0,
   warning_count: 0,
   has_csv_results: true,
   results_uri: "/organizations/d4327916-xxxx-xxxx-xxxx-b74833ce8087/imports/bulk_users/cd400bc0-xxxx-xxxx-xxxx-c79a7c93416f/results_csv"
}

Next steps

• Run this code example from our Quickstart or launcher projects: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.
• Learn How to create a new active eSignature user for details on how to create a new active organization user.
• See How to bulk export user data for details on how to use bulk export to create or update large numbers of user accounts within an organization or to verify your account users and their permissions.
• See Docusign Admin concepts for more information on Docusign Admin capabilities and features.
• See Go-Live to find the base path for Docusign Admin API calls in the production environment.