Imports

User profiles can be imported using the ReachFive Console. This import allows to create new and ready-to-use users, or to update existing users.

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

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

JSON import

{
  "external_id": "1",
  "email": "foo@gmail.com"
} (1)
{
  "email": "bar@gmail.com",
  "name": "Joe",
  "gender": "M",
  "identities": [ { "provider": "facebook", "user_id": "123" } ]
}
1 Each profile must separated by a line feed character (\n).

The schema for the imported user is a regular user object as defined for the API.

In this format, all fields are optional.

Parsing is not the only validation, please refer to the validation section below for more information about Profile validation.

CSV import

The CSV format uses a free format where columns are flattened JSON paths.

For example a path { "foo" : { "bar" : "test" } }` will become foo.bar in the CSV header.

If a column has no value, then the corresponding field will not be used for the current line.

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

Validation

Once parsed, every imported profile is then validated to ensure only consistent data is imported.

Profile import files must comply with the following requirements:

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

    • email (verified or unverified),

    • phone_number (if the SMS feature is available, verified or unverified),

    • a valid provider

  • At most a single matching profile should be returned for merging. The matching is made on:

    • uid (corresponding to the profile id),

    • email (verified or unverified),

    • phone_number (if the SMS feature is available, verified or unverified),

    • 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, only for users who have never logged in.

Allowed algorithms are:

  • bcrypt

  • md5 (with optional salt and iterations parameters; salt used as prefix)

  • sha1 (with optional salt parameter used as postfix)

  • sha256 (with optional salt and iterations parameters; salt used as prefix)

  • sha512 (with optional salt parameter used as postfix)

  • sha512Prefixed (with optional prefix and salt parameters; prefix used as prefix, salt used as postfix)

  • drupalSha512 (with no optional parameters)

  • sha256PostSalt (with option salt and iterations parameters; salt used as prefix)

  • magentoSha256 (with no optional parameters)

  • plaintext

We are able to develop new algorithms to ensure full compatibility with your current database.

 
{
  "prefix": "...",
  "value": "...",
  "algorithm": "sha512Prefixed",
  "salt": "..."
}
email,password_hash.value,password_hash.algorithm,password_hash.iterations,password_hash.salt
a1@a.aa,$S$5T/ViD4qlx6qHTQAci8eEbCuP/MVsoO8OSfU.xJsykqT5H6BXowl,sha256PostSalt,10,azdAAZeQw

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.

The profile will be completed with information from the provider after the first login of the user using the corresponding social provider.

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:

  • id (corresponding to the profile id),

  • email (verified or unverified),

  • phone_number (if the SMS feature is available, verified or unverified),

  • provider

A profile should never match more than one other profile, or an error will be returned, since there is no way to know the merge priority in a 3+ way merge.

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

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

Limitations

There is no way to define to which provider an email or phone_number belongs 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.