0

User import

User’s profiles can be imported in the administration console. This import allows to create new ready-to-use users, or to update already created users.

The import is sequential, meaning that a single import file can have a profile creation followed by an update to the same profile.

File format

The profiles can be imported either in a JSON file, or in a CSV file.

JSON file format

Each profile should be separated by a line feed character: \n.

For example:

{
  "external_id": "1",
  "email": "foo@gmail.com"
}
{
  "email": "bar@gmail.com",
  "name": "Joe",
  "gender": "M",
  "identities": [ { "provider": "facebook", "user_id": "123" } ]
}

The format for the imported user is a regular user object as defined for the API. Every field of the format is optional and can be omitted.

CSV format

The CSV format use a free format where column are flatten JSON format path.

For example a path { "foo" : { "bar" : "test" } } will become foo.bar in the CSV header. If a column has no value, the corresponding field will be considered not used for the current line.

The same import as above would look like this in a CSV format:

external_id,email,name,gender,identities.provider,identities.user_id
1,foo@gmail.com,,,,,
,bar@gmail.com,Joe,M,facebook,123

Validation

Once parsed, every imported profile is then validated to enforce that only coherent data is imported.

A few rules should be respected during this import:

  • At least an unique field should be provided (several can be provided):

    • email (verified or not verified),
    • phone_number (if the SMS feature is available, verified or not verified),
    • a valid provider
  • At most a single matching profile should be returned for merging. The matching is made on:

    • profile_id,
    • email (verified or not verified),
    • phone_number (if the SMS feature is available, verified or not verified),
    • provider
  • Only one other profile can match the imported profile. If more than one user is matched we can’t automatically define how to merge them, so an error will be returned.
  • Any provided consent should be defined for an existing key with a date anterior to the current date.
  • Any provided custom field should be defined for an existing key.
  • Any provided password hash should specify a valid hash method.

Import and merge logic

Security

Password hashes can be provided during the import under the password_hash field. Allowed algorithms are:

  • Bcrypt
  • MD5 (with optionnal salt and/or optionnal iterations)
  • SHA256 (with optionnal salt and/or optionnal iterations)
  • Plain text

For example:

{
  "value": "..",
  "algorithm": "sha256",
  "salt": "...",
  "iterations": 1000
}

If a plain text password is used, the password will be hashed during the import using the bcrypt algorithm.

If a hashed password is used, the password will be hashed using the bcrypt algorithm only after the first login of the corresponding user.

Social login

Multiple social logins can be imported under the identities field. The provider name should be a valid provider name, and the user_id field should be the ID of the user on the provider’s website.

Merge

If a corresponding profile is found, then the profile will not be created but merged with the found profile. The matching is made on the following fields:

  • profile_id,
  • email (verified or not verified),
  • phone_number (if the SMS feature is available, verified or not verified),
  • provider

The priority of the merge is defined by the attribute updated_at. If the attribute is not present on the both profile, the existing profile has priority over the imported profile during the merge.

The merge is a safe merge, meaning that (following the priority) no field will be overwritten. Field can either be completed when they are lists or free objects (consents, custom_fields), created if empty, or ignored if already defined.

Limitations

At the moment, the import is linked to the file’s upload and thus linked to the browser window. If the window is close, the update will be aborted.

There is no way to define to which provider an email or phone_number belong to. Keep in mind that after the first login using a social provider the profile’s information will be updated using the provider’s own information, completing the missing fields of the profile.