Skip navigation

Import Users

Last Updated: April 4th, 2019


The Import Users feature is used both to import batches of new users, and to update or delete existing users.


Duo's Import Users tool imports user information from a properly formatted comma-separated values (CSV) file. This streamlined process makes it easy to create, update, or delete many users at the same time.

CSV import values can include username aliases, email addresses, full names, groups, notes, and multiple phones or mobile devices. Manage users created via import from the Duo Admin Panel immediately after being created. This differs from the Bulk Enroll Users tool, in that those entries are initially limited to username and email address, and those users cannot be managed in Duo until they've completed self-enrollment.

Role required: Owner, Administrator, or User Manager.

Creating the CSV File

The CSV file can include multiple data fields for each Duo user.

Allowed Fields

The fields allowed in this CSV file are:

  • username
  • realname
  • alias[1…4]
  • email
  • phone[1…n]
  • platform[1…n]
  • group[1…n]
  • status
  • notes
  • firstname
  • lastname

Only the username field is mandatory; all other fields are optional, and can be arranged in any order (as shown in the CSV File Format section below). Duo usernames and username aliases should have unique values for each user.

The username, realname, alias[1…4] and notes values may include spaces, numbers, and punctuation.

Import up to four username aliases per user with alias1, alias2, etc. columns. Username aliases provide additional login usernames for each user, using the same authentication factors and without consuming multiple Duo licenses per username. Be sure your username aliases represent user attributes with unique values, like email addresses or UPN usernames.

The email value must be a correctly formatted SMTP address (

The phone number may include spaces, dashes, or parentheses; all non-numeric characters are deleted during import. If the phone number includes an extension, the extension can be preceded by either a # or an x. A country code can be prepended to the phone number using a +. Multiple phones can be attached to a user by including columns for phone1, phone2, etc.

The platform must be a value from the following list: mobile, smartphone, landline, blackberry10, iphone, android, or windows phone. If a platform value is not defined for a phone, the default value is smartphone. If you include a platform field, you must include a matching phone field; e.g., if you specify platform1, you must also specify phone1 (but you can specify a phone without specifying a platform for it.)

Note: smartphone should only be chosen if you know that the user has a smartphone, but don't know which kind it is. If the user has a basic mobile phone or "feature phone," then chose mobile. Having an accurate value for this field will make it easier for your users to install and activate Duo Mobile. It will also be easier to administer your system.

Users can be organized into Duo groups by specifying a group. A single user can be added to multiple groups by including columns for group1, group2, etc. If the CSV file lists groups that don't already exist in Duo, they are created automatically.

The status must be (active, disabled, bypass, or delete). If the user's status is not specified, it defaults to active, requiring the user to use two-factor authentication. If the status is set to bypass, that user is able to login without using two-factor authentication. A disabled user is not able to log in at all. (Learn more about Duo user statuses.) The delete status removes the user from Duo on import.

The notes field has a maximum length of 512 characters.

The firstname and lastname information is required by Duo's ID Proofing feature for Epic EPCS. It is not necessary to populate these fields if you aren't using ID Proofing in your deployment.

CSV File Format

The first line of the CSV file (the header) specifies the fields to import. For example:


Here are some examples of possible user entries in this CSV file using the example header. Notice that when there is no value for a field, the field is left blank.

jason,Jason Smith,jason@domain.local,,jason.smith,smithj,,,734-555-1234,Android,734-555-4343x222,Stdusers,
sally,Sally Jones,,,,,,Bypass,734-555-1235,,,StdUsers,
jack,Jack Johnson,,,,,,,734-555-4322,Mobile,440-555-1234,Stdusers,NetAdmins

Here is a sample CSV file that you can use as a template for creating your own.

The CSV file size should not exceed 1 MB. If you need to import many users, split the information up into multiple CSV files of 1 MB or less and import each one separately.

Importing Users


When you import a user with the same username as an existing Duo user who is not already managed by directory sync, the imported values always overwrite the existing values.

CSV import does not modify or update users managed by directory sync.

Once you've created your CSV file, you're ready to import your users.

  1. Log in to the Duo Admin Panel and click Users in the left sidebar.

  2. Click the Import Users button near the top of the page. Now click the Choose File button, browse to your CSV file, and select it. Click Upload to start the import process.

    Choose CSV File

  3. If the CSV file contains any errors, the import attempt fails and you are shown a red error message like the one below. If you see an error message, then the attempt has failed and none of your users were imported. Correct the indicated errors and try the import again.

    CSV Import File Error

  4. Wait for the import to complete. Importing users via CSV can take some time, particularly if there are a large number of entries. You can leave the Import Users page running in the background. Periodically check back or refresh the page for progress updates, which will appear in a bar near the top of the Import Users page:

    CSV Import Progress

    Note: Only one CSV import can be running at any given time.

  5. After the CSV import is finished, a success message at the top of the Duo Admin Panel reports the results:

    Import Status

There are few circumstances under which an import can succeed even though updates to one or more accounts failed. An example of this is attempting to delete an account that does not exist. These will be noted in the success message.

Updating Users

Remember: When you import a user with the same username as an existing Duo user, values specified in the CSV file always overwrite the existing values.

For example, suppose you have a Duo user with the username TestUser1 who has no other information associated with the account. If you were to import a CSV containing a row with the same username (TestUser1), but this time also including a real name, username alias, email address, phone number, etc., this information would replace the existing (blank) information for that user.

TestUser1,Test User 1,tuser1,,,734-555-1234,Android

The situation is the same if the Duo user has existing information. Suppose some properties for TestUser1 are already populated, like username alias, real name, email address, phone numbers, groups, etc. Now you want to add this user to a new group, TestGroup1. If you modify your CSV to include this new group value for TestUser1 (but leave all other values as they were), the user is added to the new group while keeping all other information intact. This can be done for any number of users in a CSV file, and for any of the fields. Note that you can't remove group memberships via CSV import.

TestUser1,Test User 1,tuser1,,,734-555-1234,Android,TestGroup1

Deleting Users

If you want to delete an existing Duo user, you can do so by setting the user's status to delete in the CSV file. If that user is the only user attached to a specific phone, then the phone will also be deleted from Duo when the CSV file is imported.


Activating Devices for Newly Imported Users

After importing new users, the next step is to activate their devices for use with Duo. If you defined the users' device platforms as part of the import, then the Users page displays a bar indicating that some users have not yet activated Duo Mobile. Clicking the link in this bar starts the process of sending activation links. You can choose which users you want to receive links, and whether to send the activation via email or text.

Activation Links

For more information on user activation for imported users, see Activating Duo Mobile After Enrollment.


Need some help? Try searching our Knowledge Base articles or Community discussions. For further assistance, contact Support.