Exporting your users with the API

The reporting tools in Zendesk can export your users in CSV, JSON, or XML formats. However, these tools are not available to customers on Team plans.

As an alternative, customers on all Zendesk plans including Team plans can use the Zendesk REST API to export lists of their users.

In this how-to article, you'll create a small Python script that exports all the users in your account to a CSV file. You can then import the CSV file into your favorite spreadsheet application.

If you're uncomfortable working with code, you may want to ask for help from someone with greater technical proficiency or from your favorite AI chat bot.

Disclaimer: Zendesk provides this article for instructional purposes only. Zendesk doesn't provide support for the example code in this article. Zendesk doesn't support third-party technologies such as command-line tools or Python.

Prerequisites

Zendesk account

Ensure you have access to a Zendesk account and that you've been assigned the role of admin or agent in the account.

Zendesk API token

1. Sign in to your Zendesk account.
2. Navigate to the Admin Center.
3. Go to Apps and integrations > APIs > Zendesk API.
4. If not already done, click the Settings tab and enable Token Access.
5. Click Add API Token, give it a name, and save the token somewhere secure (you'll need it later).

Python

Python is a high-level, general-purpose programming language. It's one of the easiest languages to learn and use.

Download and install the latest version of Python for your operating system at https://www.python.org/downloads/.

Terminal

Terminal is a command line tool that's already installed in Windows and macOS.

Windows

1. Click the Start Menu (Windows icon) in the taskbar or press the Windows key on your keyboard.

2. Type "Terminal" in the search bar.

3. Right-click Terminal in the search results and choose Run as administrator.

4. Allow Terminal to run scripts by entering Set-ExecutionPolicy -ExecutionPolicy Unrestricted at the command line and pressing Enter.

You only have to run Terminal as an administrator and set the execution policy one time.

If you use Windows 10 or earlier, you can use the command prompt instead. Press Windows + R to open the Run dialog, then type cmd and press Enter.

macOS

1. Open Finder and go to Applications/Utilities.

2. Double-click Terminal.

Setting up your project

1. Create a folder called export_users.

2. Navigate to the folder using Terminal.

   For example, if you created your export_users folder in the Documents/projects folder, then run one of the following commands in Terminal and press Enter:

   • Windows: cd Documents\projects\export_users
   • Mac or Linux: cd Documents/projects/export_users

   The command cd means "change directory".

3. Create a virtual environment by entering one of the following commands in Terminal:

   • Windows: py -m venv venv
   • macOS or Linux: python3 -m venv venv

   A virtual environment allows you to install Python libraries just for this project so that you don't clutter the rest of your system with multiple conflicting Python libraries.

4. Activate the virtual environment by running one of the following commands:

   • Windows: venv\Scripts\activate
   • Mac or Linux: source venv/bin/activate

   You should now see "(venv)" at the start of the line in Terminal.

   

5. Install the requests library by running the following command:

   python -m pip install requests

   The requests library is a Python library that makes API requests easier.

Create the export script

1. Create a file named export_users.py.

2. Paste the following code into the file:

   import csv
   import time
   import requests
   
   
   ZENDESK_USER_EMAIL = 'your_zendesk_email'
   ZENDESK_API_TOKEN = 'your_zendesk_api_token'
   ZENDESK_SUBDOMAIN = 'your_zendesk_subdomain'
   
   def main():
       print('Getting users from Zendesk...')
       users: list = []
       url = f'https://{ZENDESK_SUBDOMAIN}.zendesk.com/api/v2/users.json'
       params = {'page[size]': 100}
       auth = f'{ZENDESK_USER_EMAIL}/token', ZENDESK_API_TOKEN
       response = requests.get(url, params=params, auth=auth)
       page = response.json()
       users.extend(page['users'])
       while page['meta']['has_more']:
           params['page[after]'] = page['meta']['after_cursor']
           response = requests.get(url, params=params, auth=auth)
           if response.status_code == 429:    # if rate limit reached
               time.sleep(int(response.headers['retry-after']))
               response = requests.get(url, auth=auth)
           page = response.json()
           users.extend(page['users'])
       
       write_to_csv(users)
   
       print('Done!')
   
   
   def write_to_csv(users):
       with open('users.csv', 'w', newline='') as file:
           writer = csv.writer(file)
           writer.writerow([
               'Name', 
               'Email'
               ])
           for user in users:
               writer.writerow([
                   user['name'], 
                   user['email']
                   ])
   
   
   if __name__ == "__main__":
       main()

   Make sure to preserve the code's indentation, which matters in Python.

3. Edit the file to change the values of the three constant variables at the top of the file (the ones in upper case) to values that apply to you.

Export the users

1. If not already done, navigate to the project folder using Terminal:

   • Windows: cd Documents\projects\export_users
   • Mac or Linux: cd Documents/projects/export_users

2. If not already done, activate the virtual environment:

   You should see "(venv)" at the start of the line in Terminal. If not, activate the virtual environment:

   • Windows: venv\Scripts\activate
   • Mac or Linux: source venv/bin/activate

3. Export your users by running the following command:

   python export_users.py

   The script will create a users.csv file in your project folder.

4. Import the CSV file into your favorite spreadsheet application.

Customizing your CSV file

You can add more columns to the CSV file by adding items to the two lists in the write_to_csv() function definition. The first list defines the heading row in your CSV file. The second list defines the rest of the rows in the file.

The number and order of the items in the two lists must match exactly to correctly display the data in your CSV file.

The following example adds a CSV column for the user 'role':

def write_to_csv(users):
    with open('users.csv', 'w', newline='') as file:
        writer = csv.writer(file)
        writer.writerow([
            'Name',
            'Email',
            'Role'
            ])
        for user in users:
            writer.writerow([
                user['name'],
                user['email'],
                user['role']
                ])

Each item in each list must end with a comma except for the last list item.

The terms 'name', 'email', and 'role' are defined in the API reference docs. They correspond to possible columns in your users table. For all possible columns you can add to your CSV file, see the following reference in the Users API docs:

https://developer.zendesk.com/api-reference/ticketing/users/users/#json-format