Blog
Home/

V2 Users:list Paging Change

Larry Kluger
Larry KlugerDocuSign Lead Product Manager for Partner Platforms
Summary5 min read

This eSignature REST v2 API method will be updated with a potentially breaking change.

    • Summary
    • Decision tree
      • The Users:list method
      • API change and timetable
        • Your action is required
          • eSignature REST API v2.1 Users:list
          • Code examples

        Table of contents

        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 
        
        <h2>I’ve got questions</h2>
        
        <p>If you have any questions about this update, please contact the <a href="https://support.docusign.com/">Docusign Developer Support</a> group.</p>
        
        <h2>Why is this change needed?</h2>
        
        <p>Returning <code>Users:list</code> results 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.</p>
        
        <h2>Additional resources</h2>
        
        <ul><li><a href="https://developers.docusign.com/">Docusign Developer Center</a></li>
        	<li><a href="https://twitter.com/docusignapi">@DocuSignAPI on Twitter</a></li>
        	<li><a href="https://www.linkedin.com/showcase/docusign-for-developers/">Docusign for Developers on LinkedIn</a></li>
        	<li><a href="https://www.youtube.com/playlist?list=PLXpRTgmbu4opxdx2IThm4pDYS8tIKEb0w">Docusign for Developers on YouTube</a></li>
        	<li><a href="https://developers.docusign.com/#newsletter-signup">Docusign Developer Newsletter</a></li>
        </ul>
        
        Larry Kluger
        Larry KlugerDocuSign Lead Product Manager for Partner Platforms

        Larry Kluger has over 40(!) years of tech industry experience as a software developer, developer advocate, entrepreneur, and product manager. An award-winning speaker with a 48K StackOverflow reputation, he enjoys giving talks and helping the ISV and developer communities.

        Twitter: @larrykluger

        LinkedIn: https://www.linkedin.com/in/larrykluger/

        More posts from this author

        Related posts

        • Developers

          Introducing OAuth for Connect: enhanced security for webhooks

          Alan Roza
          Alan Roza
        • Updated Docusign University Learning Portal for Developers

          Sasha Vodnik
          Sasha Vodnik
        • Recipient Connect

          Larry Kluger
          Larry Kluger

        Introducing OAuth for Connect: enhanced security for webhooks

        Alan Roza
        Alan Roza

        Updated Docusign University Learning Portal for Developers

        Sasha Vodnik
        Sasha Vodnik

        Recipient Connect

        Larry Kluger
        Larry Kluger

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

        Explore Docusign IAMTry eSignature for Free
        Person smiling while presenting