User Import CSV File Format Last update: 2023-02-26 17:48:05

Requirements for the CSV file

• The CSV file needs to be a plain text file UTF-8 encoded
• The first line of the CSV file needs to hold the field names, or the fields to be imported needs to be in correct order (please see samples below)
• Each row is in a new line
• Each column is separated with a field delimiter character
• At least the email address is provided

The minimum of required CSV fields for importing users

To import users you need to provide a CSV file with at least 1 field: email - that's it!

"vader@imperium.com"
"jane.doe@mail.com"
"john.doe@mail.ru"
"sponge.bob@bottom.at"
"han.solo@rebels.org"

In this case the import engine automatically sets the email address as username (if you check the Set Email Adress as Username option, you can overrule eventually existing username values at any time).

Description of all supported import fields

Full row of user fields in correct order

email,username,password,fullname,phone,mobilephone,dob,gender,address,country,city,state,zip,fax,photo,comment,website,extended

Field properties

User Import supports two ways of CSV file formatting:

1. First line of CSV file contains field names (header row)
   (This is the comfortable and recommended way!)
2. Without header row but fields in fixed order.

Method 1: Formatting the CSV file with first line containing field names

This is the recommended way of importing users!

Minimum required field: email. Furthermore you can provide as much fields as you need in any order you like. You don't need to fill the gaps of un-needed fields.

Sample

You want to import users with the following fields: email, username, fullname, firstname, lastname. (if you wonder about the last to fields, please keep on reading):

"email","username","fullname","firstname","lastname"
"vader@imperial.com","vader","Darth Vader","Darth","Vader"
"jane.doe@mail.com","janedoe","Jane Doe","Jane","Doe"
"john.doe@mail.ru","johndoe","John Doe","John","Doe"
"sponge.bob@bikinibottom.at","spongebob","Bob Sponge","Bob","Sponge"
"vaderjunior@imperial.com","vaderjunior","Darth Vader Jun.","Darth","Vader"
"han.solo@rebels.org","hansolo","Han Solo","Han","Solo"

You probably have already recognized the 2 fields firstname and lastname, which you know aren't valid user object fields.
And here comes the magic:
Each fields you provide, which aren't in the list of valid user object fields, are treated and saved as extended fields! Isn't this cool?

Method 2: Formatting the CSV file without header row but fields in fixed order

Minimum required field: email. Furthermore you can provide as much fields as you need. Un-needed fields between the first and the last used field needs to be provided as blank values.

Sample

You want to import users with the following fields: email, username, fullname, gender, address, country, city, state, zip, photo. One row of the CSV file would look like this (for better understanding we are using the field names as values):

"email","username","fullname",,,,"gender","address","country","city","state","zip",,"photo"

Full sample with extended fields

You want to import users with the following fields: email, username, fullname, gender, address, country, city, state, zip, photo, website, extended. The full CSV file would look like this (in the following sample we are using single quotes as field enclosure characters and semicolons as field delimiters because of Json formatted strings in last field):

'vader@imperial.com';'vader';'Darth Vader';;;;1;'Sector 1';'A Far Galaxy';'Deathstar';'Area 17';2233;;'pic1.jpg';;'http://darkside.vader.com';'{"firstname":"Darth","lastname":"Vader"}'
'jane.doe@mail.com';'janedoe';'Jane Doe';;;;2;;;;;;;'pic2.jpg';;;'{"firstname":"Jane","lastname":"Doe"}'
'john.doe@mail.ru';'johndoe';'John Doe';;;;1;;;;;;;'pic3.jpg';;;'{"firstname":"John","lastname":"Doe"}'
'sponge.bob@bikinibottom.at';'spongebob';'Bob Sponge';;;;1;'Bikini Bottom 37';;;;;;'pic4.jpg';;;'{"firstname":"Bob","lastname":"Sponge"}'
'vaderjunior@imperial.com';'vaderjunior';'Darth Vader Jun.';;;;1;'Sector 1';'A Far Galaxy';'Deathstar';'Area 18';2233;;'pic5.jpg';;;'{"firstname":"Darth","lastname":"Vader"}'
'han.solo@rebels.org';'hansolo';'Han Solo';;;;1;;;;;;;'pic6.jpg';;;'{"firstname":"Han","lastname":"Solo"}'

Extended fields in the above sample:
If you want to import extended fields without providing a header row in your CSV file, you need to provide this extra fields in form of a Json formatted string. Extended fields can also be nested. If you don't know what's a Json string, please have a look at the official json.org website!