Skip to navigation
How-to guides

How to bulk export user data

View as Markdown

This topic demonstrates how to bulk export user accounts within an organization into a CSV (comma separated value) file.

Run this code example from our Quickstart or launcher projects: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.

Required data

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

Data elementDescription
{ACCOUNT_ID}A GUID value that identifies the account to which the user will be added.
To determine your account IDs, open your Organization home page in Docusign Admin, then select the Accounts tile. The Account ID values for each account in your organization will be shown on the resulting page.
Admin accessThe caller must be at least one of the following:
  • A full organization administrator
  • A delegated organization administrator
See Organization Administrators for details on Docusign Admin roles.
{BASE_PATH}A string value that forms the root of the URL required to make API calls. The base path value in the example code is set to target the developer environment at
https://<domain>/management
Where <domain> is api-d.docusign.net for the developer environment and api.docusign.net for production.
{ORGANIZATION_ID}A GUID value that identifies the the organization that contains the account to which the user will be added. Copy the value from the Organization ID field in the Organization section of the Account Profile page.

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.

See Docusign Admin Authentication for details and the full list of Docusign Admin scopes.

Three icons that represent the three methods a user can use to obtain an OAuth token: JSON Web Token (JWT), Public Authorization Code Grant (ACG), and Confidential Authorization Code grant

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 export request

Next, begin the process of creating the bulk export list by calling the createUserListExport endpoint. You can retrieve the resulting CSV data in a future step.

Creating and provisioning the bulk export list can take some time, especially for large organizations spread out over several regions. You can check the status of your bulk export request by calling the getUserListExport endpoint, as demonstrated in the next step.

You can filter the users that will be added to the generated bulk export user list using the type parameter of the request body, which specifies the category of users within your organization that will be added to the generated list of user data. Possible values are:

  • organization_external_memberships_export: Returns a list of users with email addresses that are part of your organization’s domain(s), but with memberships in accounts that are not part of your organization.
  • organization_memberships_export: Returns a list of all users with memberships in your organization’s accounts.
  • organization_domain_users_export: Returns a list of all users within your organization’s domain(s).
retryCount=0
downloadUrl=''
while [ $retryCount -le 5 ]; do
    echo ''
    echo 'Retrieving Bulk Action Status...'
    echo ''
    curl --request GET ${base_path}/v2/organizations/${ORGANIZATION_ID}/exports/user_list/${requestId} \
        "${Headers[@]}" \
        --output ${response}
    echo ''
    echo "Response:"
    echo ''
    cat $response
    echo ''
    #Check the status of the Bulk Action
    status=$(cat $response | grep status | sed 's/.*\"status\":\"//' | sed 's/\",.*//')
    echo "Status: $status"
    if [ "$status" = "completed" ]; then
        echo ''
        echo 'Bulk Request has been completed'
        echo ''
        downloadUrl=$(cat $response | grep url | sed 's/.*\"url\":\"//' | sed 's/\",.*//')
        echo "Download Url: $downloadUrl"
        let retryCount=6
    else
        echo ''
        echo 'Bulk Request has not been completed. Retrying in 5 seconds'
        echo ''
        sleep 5
        let retryCount=retryCount+1
    fi
done

Expected response

After a successful request, you will receive a response similar to this.

The important parts of the response are highlighted below:

PropertyDescription
idIdentifies the request. You can use this value to check the status of the export request again, if its status is not yet completed.
statusThe status of the request. If the bulk export data is still being created, this value will be queued or in_progress. When the bulk export data is ready, this value will be completed.

Possible values are:
  • unknown: Unknown status.
  • queued: Ready to be created.
  • in_process: The export is being created.
  • completed: The export was created.
  • failed: The export could not be created.
metadata_urlThe endpoint URL that you can call to check the request status and, if it is completed, get a download link for the export data.

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 the user_read scope.
  • Make sure that the calling user has admin rights.
Sample response
{
  "id": "f7638356-xxxx-xxxx-xxxx-4935e87d88c1",
  "type": "organization_memberships_export",
  "requestor": {
    "name": "1007 a",
    "id": "9cb13e29-xxxx-xxxx-xxxx-6baeba17505c",
    "type": "user",
    "email": "1007a@example.com"
  },
  "created": "2021-10-07T22:16:16.4923965Z",
  "last_modified": "2021-10-07T22:16:16.4923965Z",
  "status": "queued",
  "metadata_url": "https://api-d.docusign.net/management/v2/organizations/e1b55b52-xxxx-xxxx-xxxx-8a7ff52dd8e0/exports/user_list/f7638356-xxxx-xxxx-xxxx-4935e87d88c1",
  "percent_completed": 0,
  "number_rows": 0,
  "size_bytes": 0
}

Step 4. Check the request status

It can take some time for a bulk user export request to be fully created, depending on the number of users that it contains and the regions it encompasses. You can call the getUserListExport endpoint 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 export data.

Important: Be sure to replace the requestId value in the request with the ID of the bulk user export request that you created in the previous step.

curl --request GET ${base_path}/v2/organizations/${ORGANIZATION_ID}/exports/user_list/${requestId} \
    "${Headers[@]}" \
    --output ${response}

Expected response

This call will return a response similar to this.

The important parts of the response are highlighted below:

PropertyDescription
idIdentifies the request. You can use this value to check the status of the export request again, if its status is not yet completed.
statusThe status of the request. If the bulk export data is still being created, this value will be queued or in_progress. When the bulk export data is ready, this value will be completed.

Possible values are:
  • unknown: Unknown status.
  • queued: Ready to be created.
  • in_process: The export is being created.
  • completed: The export was created.
  • failed: The export could not be created.
successIndicates whether the export was successful. If false, the export failed and the data cannot be downloaded.
percent_completedIndicates how close to completion the export request is.
results.idThe ID of the generated user list data.
results.urlThe URL that you can call to download the exported list of user data, as demonstrated in the next step.
Sample response
{
  "id": "f7638356-xxxx-xxxx-xxxx-4935e87d88c1",
  "type": "organization_memberships_export",
  "requestor": {
    "name": "1007 a",
    "id": "9cb13e29-xxxx-xxxx-xxxx-6baeba17505c",
    "type": "user",
    "email": "1007a@example.com"
  },
  "created": "2021-10-07T22:16:16.4923965Z",
  "last_modified": "2021-10-07T22:16:37.4462418Z",
  "completed": "2021-10-07T22:16:37.4462418Z",
  "expires": "2022-01-05T22:16:32.1492867Z",
  "status": "completed",
  "metadata_url": "https://api-d.docusign.net/management/v2/organizations/e1b55b52-xxxx-xxxx-xxxx-8a7ff52dd8e0/exports/user_list/f7638356-xxxx-xxxx-xxxx-4935e87d88c1",
  "percent_completed": 100,
  "number_rows": 182,
  "size_bytes": 57403,
  "results": [
    {
      "id": "3cc60fdb-xxxx-xxxx-xxxx-1467a90d6d36",
      "site_id": 1,
      "url": "https://demo.docusign.net/restapi/v2/organization_exports/e1b55b52-xxxx-xxxx-xxxx-8a7ff52dd8e0/user_list/3cc60fdb-xxxx-xxxx-xxxx-1467a90d6d36",
      "number_rows": 182,
      "size_bytes": 57403
    }
  ],
  "success": true
}

Step 5. Download the exported user data

After the export is complete and you’ve obtained the URL to retrieve the bulk export data, you can download a CSV file of that data.

The results.url value returned by the status request made in the previous step will contain the full path for the URL where you can download the CSV data, but you can also create the request manually by calling the getUserListExport endpoint, as demonstrated in this example.

curl --request GET "${downloadUrl}" \
	"${Headers[@]}" \
	--output ${response2}

Expected response

Important: Make sure to replace the resultId placeholder with the results.id value you obtained in the previous step (or copy and paste the results.url value to completely replace the URL).

This API call will return a CSV file containing the list of user data, similar to this.

After downloading the CSV file, you can make edits to the list and either reimport it to update your user data or import it to a new account or organization. See How to add users via bulk import for details.

View the source code for this how-to on GitHub: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby

Sample response
"SiteID","AccountID","AccountName","APIUserName","FullName","FirstName","LastName","UserEmail","UserStatus","AddedDate","MembershipStatus","eSignPermissionProfile","CompanyName","JobTitle","AddressLine1","AdressLine2","City","StateRegionProvince","PostalCode","Country","Phone","Groups","EnableCLM","CLMPermissionProfile","IdentityProviderInfo","eSignPermissionProfileID","CLMPermissionProfileID"
"1","2255f473-xxxx-xxxx-xxxx-c07c9abc6d76","Test User","4c084b7a-xxxx-xxxx-xxxx-bf36f69e5c4e",1007 a","1007","a","1007a@example.com","Active","8/25/2021 12:3:04 AM","Active","profile1","","","","","","","","","","[Administrators],[group1],[Everyone]","False","","","10xxxx53",""
"1","2255f473-xxxx-xxxx-xxxx-c07c9abc6d76","Test User","e3e72e73-xxxx-xxxx-xxxx-064592a3453b",1007 a","1007","a","1007a@example.com","Active","8/24/2021 9:24:56 M","Active","profile2","","","","","","","","","","[Everyone]","False","","","10xxxx74",""

Next steps