V2 Users:list Paging Change

Summary

Does your eSignature REST API v2 application use the Users:list API method to list 500 or more users? Then an upcoming API change may be a breaking change for your application.

Decision tree

The API change will only affect a small minority of applications. Use this decision tree to determine if your application will be affected:

• Does your application use eSignature REST API v2?No: this change does not affect you.Yes: continue.

• Does your application use the REST API v2 Users:list method to obtain a list of the users in an account?No: this change does not affect you.Yes: continue.

• Do you use the REST API v2 Users:list method with pagination? (Do you use the count query parameter?)Yes: this change does not affect you.No: continue.

• Do any of the accounts used with the v2 Users:list method have more than 500 users or may eventually reach more than 500 users?No: this change does not affect you.Yes: the upcoming changes to the eSignature REST API v2 Users:list method will affect your application. See below for more information.

The Users:list method

The Users:list method lists the users in an account. The request can include optional query parameters to limit the response. For example, the response can be limited to account users whose email addresses match a pattern. Query options can also enable additional information to be included in the response data such as the current login status for the users.

The API method supports paging via the count and start_position query parameters along with the endPosition, resultSetSize, startPosition, totalSetSize, and nextUri attributes in the response data. Paging is the common API technique of returning a subset of the total result set. Multiple API calls are made to retrieve the entire result set.

API change and timetable

The API v2 Users:list API method will be updated to require pagination:

• The default page size will become 500. That is, the default value of the count request parameter (the page size) will become 500.

• If the count parameter is set, then it must be between 1 and 500, inclusive. This will be a change, currently the maximum count setting is 100. When you implement paging, Docusign recommends that you use a count setting (page size) of 50 records.

Starting June 15, 2021, any newly created production integration keys will be affected by this change in production.

Existing integration keys that use API v2 Users:list and have only had responses with less than 500 users since February 1, 2021 will be updated on June 15, 2021 to the changes listed above. These applications should not see any difference in behavior since their total result sets are not more than 500, the new default page size.

All other existing and new integration keys in the Developer system (demo) will be updated on May 18, 2021 to the changes listed above.

Docusign Customer Service is contacting all customers and ISVs that have existing integration keys that use API v2 Users:list and have had Users:list responses with more than 500 records since February 1, 2021. Docusign Customer Service will work with each customer and ISV to understand when their integration key and associated application can implement paging for the Users:list API method. After the application is updated by the customer or ISV, the integration key will be set to use the changes listed above.

Your action is required

• Your application uses the v2 Users:list API method without paging and your total response record set is much fewer than 500: no action is immediately required, but the next time you update your application, you should update to API v2.1, with paging, for the Users:list method.

• Your application uses the v2 Users:list API method without paging and your total response record set can be more than 500: You will need to update your application to use paging for the Users:list method. Docusign recommends that you also update to v2.1 of the API as shown by the examples below. Docusign will work with you to ensure that paging will not be required for your application until you’re ready.

• You’re building a new REST API application and plan to use the Users:list API method: be sure to use REST API v2.1 and implement paging for the Users:list API method.

eSignature REST API v2.1 Users:list

The v2.1 Users:list API method already requires pagination. The default page size is 50 with a maximum of 100. The v2.1 Users:list API method is not being changed.

Code examples

This code example for the Users:list API method uses paging to retrieve the total result set via (potentially) multiple API calls.

This example uses Python and calls the API directly.

## Call the List Users API
import requests
import json
access_token = 'abcdefghijk'
base_path = 'https://demo.docusign.net' # obtain via /oauth/userinfo
account_id = 'xxxxxxxxxxxxxx'
list_users_basepath = f'{base_path}/restapi/v2.1/accounts/{account_id}'
 
# Let's define a page size 
start_position = 0
count = 50
nextUri = f'/users?start_position={start_position}&count={count}'
headers = {'Authorization': 'Bearer ' + access_token}

# loop until the nextUri response attribute is null 
while nextUri:
    try:
        list_users_response = requests.get(list_users_basepath + nextUri,
            headers=headers, verify=True)
        if not list_users_response.status_code == 200:
            print (f'API error: {list_users_response.text}')
            exit()
        list_users_resp_json = json.loads(list_users_response.text)
        print(list_users_resp_json['users'])
        
        nextUri = list_users_resp_json['nextUri'] if (
            'nextUri' in list_users_resp_json) else False
        print() # blank line between each API call's response
    except requests.exceptions.RequestException as e:
        print (f'Exception!')
        raise SystemExit(e)
print('Done!\n')

Node.JS SDK example

This example is for the Node.JS SDK. Applications for other SDKs will be similar. Note that the paging data in the responses are strings and must be converted to integers before being used for comparisons.

let dsApiClient = new docusign.ApiClient();
dsApiClient.setBasePath(args.basePath);
dsApiClient.addDefaultHeader('Authorization', 'Bearer ' + accessToken);
let usersApi = new docusign.UsersApi(dsApiClient)

const count = 50; // page size
let startPosition = 0;
let moreResults = true;
let output = "";
let err = false;
try {
    while (moreResults) {
        const results = await usersApi.list(args.accountId, 
            {count: count, startPosition: startPosition});
        output += `${JSON.stringify(results.users, null, '    ')}\n\n`;
        startPosition = parseInt(results.endPosition, 10) + 1;
        moreResults = startPosition < parseInt(results.totalSetSize, 10);
    }
}
catch (error) {
    err = true;
    let errorBody = error && error.response && error.response.body
        // we can pull the Docusign error code and message from the
        // response body
        , errorCode = errorBody && errorBody.errorCode
        , errorMessage = errorBody && errorBody.message
        ;
    console.log(
  `err: ${error}, errorCode: ${errorCode}, errorMessage: ${errorMessage}`);
}
if (!err) {console.log(output)};

I’ve got questions

If you have any questions about this update, please contact the Docusign Developer Support group.

Why is this change needed?

Returning Users:listresults with an unbounded number of result records can slow the Docusign platform or cause timeout errors. Requiring pagination will assist in maintaining Docusign’s platform reliability and performance.

Additional resources

• Docusign Developer Center

• Docusign Developers Community

• @DocusignDevs on X

• Docusign for Developers on LinkedIn

• Docusign for Developers on YouTube

• Docusign Developer Newsletter