How do I update users in bulk

Three ways to change many records at once: select and act in the user list, import a file with the updated values, or use the API.

Three ways to change many records at once: select and act in the user list for a straightforward change to a visible set, import a file with the updated values, or use the API where the change is complex or recurring.

Whichever you pick, test on ten first. A column mapped wrongly across ten records is a minute to fix; across ten thousand it is a cleanup project, and the records are already live. There is no bulk undo.

Update from a file

1. Export the current values first. That file is your only way back.
2. Carry every column you want to keep. An empty column in the file overwrites most existing data for that user, so a two-column file of email plus one new field wipes the rest of the profile. This is the mistake that turns a five-minute job into a restore.
3. Build the file with one unique identifier per row: an email address or an external ID. Only one is required to match an existing user.
4. Check no user appears twice. A duplicate in the same file can make the whole import fail.
5. Import the file and check the ten test records before doing the rest.

The limits on a file

The row limit is rarely what stops people. The duplicate rule is: a list assembled from two sources usually contains somebody twice, and that fails the import rather than merging the rows.

Matching is on email or external ID

Where addresses change often, or where your own system already holds an identifier, the external ID is the steadier match. An email with a typo either creates a new user or fails that row, so check the addresses before importing rather than afterwards.

What to watch for

It can fire triggers. Updating users can send notifications, so check that before touching several thousand people who were not expecting to hear from you.

New users get a welcome email. With a help centre enabled, every user created by an import receives one, containing a link to verify their address and choose a password. Turn it off first if that is not what you want: in Admin Center, People > Configuration > End users, deselect the verification email for users created by an agent or administrator.

Do it outside busy hours. Large updates take time and add load. Nothing breaks, and it is one less thing happening while the queue is full.

The common jobs

• Assigning existing users to organisations after setting up domain mapping.
• Filling a new custom field for everybody.
• Correcting names imported in the wrong format.
• Tagging a segment of customers.

See also

• Bulk importing users with the data importer
• Automatically adding users to an organisation by domain
• Custom fields on users and organisations