Bulk user import/edit

  • Updated on Jul 11, 2025
  • Published on Feb 6, 2025
  • 5 minute(s) read
  • DL
  • Migration Team
 Prev Next

Overview

Encodify enables administrators to efficiently create or update users in bulk using CSV files and REST APIs. This is ideal for managing large user bases across departments, clients, or identity providers.

Prerequisites

Before using the bulk import tool, make sure:

  • User Management is enabled on your site.

  • External API access requires both "Find user" and "Edit users" permissions. These do not require admin-level roles, making them suitable for delegated user management.

  • You're running version 9.99 or later for external API support.

API Endpoints Overview

The table below provides an overview of the API endpoints:

Action

Endpoint

Description

Get CSV Headers

GET /rest/site/{siteId}/userBulkSave/templateHeaders

Returns CSV header template

Validate CSV

POST /rest/site/{siteId}/userBulkSave/preview

Returns a preview with validation results

Execute Import

POST /rest/site/{siteId}/userBulkSave (or /external/...)

Creates or updates users

Step-by-Step: How to Import or Edit Users

1. Generate a CSV Template

Begin by generating a CSV header template using the relevant API endpoint. This provides the exact column names required for a valid import file.

  • Use the GET /templateHeaders endpoint to retrieve the header row.

  • Paste the response into the first row of your CSV file.

  • This ensures that field names are correctly aligned with the system.

Example Request

bashCopyEditcurl -X GET \
  -H "Accept: text/plain" \
  https://.../rest/site/{siteId}/userBulkSave/templateHeaders

2. Fill in User Data

After creating the template, populate the CSV file with the relevant user data to import or update. Follow these formatting rules to ensure the file is processed correctly:

  • To create new users: Set the User id to 0.

  • To update existing users: Provide a unique identifier such as User id, Login, or Email.

  • For dates: Use the format YYYY-MM-DD.

  • For list fields: Separate values using semicolons (e.g. Sales;Support).

  • To clear a field: Leave the value blank, but retain the column header.

  • To retain existing values: Omit the relevant column entirely.

  • For special characters: Enclose values in double quotes (e.g. "London, UK").

Example CSV

csvCopyEditUser id,Login,Email,Name,City,Phone,Mobile Email,Expired date,Access Right,Active,User groups,Country,IDP id,Default client_5710
0,jdoe,jdoe@example.com,John Doe,London,07700…,"jdoe.mobile@example.com",2025-12-31,Basic,t

3. Preview and Validate Your Import

Before carrying out the import, use the preview endpoint to validate your CSV content. This step helps identify any formatting issues or data errors before data is committed.

  • Upload your CSV file to the preview endpoint.

  • The response will provide a validation report for each row.

  • Review the results and make any necessary corrections before importing.

Example Request

bashCopyEditcurl -X POST \
  -H "Accept: application/json" \
  -F "file=@import.csv" \
  https://.../rest/site/{siteId}/userBulkSave/preview

After sending a preview request (POST: /rest/site/{siteId}/userBulkSave/preview), the API returns a JSON response. This represents how the CSV file is interpreted and validated — each row is converted into a user object.

Below is a sample response, where each object contains user data as interpreted from the uploaded CSV:

jsonCopyEdit{
  "result": [
    {
      "userId": 6914,
      "login": "users60",
      "email": "users60@avios.com",
      "name": "users60",
      "city": "Kyiv",
      "cellPhone": "0978535353",
      "phone": "0978535353",
      "cellPhoneEmail": "users60.mobile@avios.com",
      "address": "Zhylyanska",
      "expiredDate": "2019-12-13",
      "systemAccessName": "Basic",
      "active": true,
      "portalPage": "Dashboard",
      "siteSkin": "",
      "userGroupNames": ["Markets", "Hubs", "Carte"],
      "department": "Rad",
      "function": "Clients",
      "country": "United Kingdom",
      "region": "Unilever",
      "subRegion": "Unilever",
      "languageCode": "us",
      "idpId": 3,
      "userExternalId": "users60@avios.com",
      "customFields": {
        "Agency": "",
        "Default client": "Some",
        "User type": "",
        "Organisation type": "",
        "Count": "",
        "Client": ""
      },
      "newUiEnabled": true,
      "classicUiEnabled": true
    },
    {
      "login": "users65",
      "email": "users65@avios.com",
      "name": "users65",
      "city": "Kyiv",
      "cellPhone": "0978535353",
      "phone": "0978535353",
      "cellPhoneEmail": "users65.mobile@avios.com",
      "address": "Zhylyanska",
      "expiredDate": "2019-12-13",
      "systemAccessName": "Basic",
      "active": true,
      "portalPage": "Dashboard",
      "siteSkin": "",
      "userGroupNames": ["Markets", "Hubs", "Carte"],
      "department": "Rad",
      "function": "Clients",
      "country": "United Kingdom",
      "region": "Unilever",
      "subRegion": "Unilever",
      "languageCode": "us",
      "idpId": 3,
      "userExternalId": "users65@avios.com",
      "customFields": {
        "Agency": "",
        "Default client": "Some",
        "User type": "",
        "Organisation type": "",
        "Count": "",
        "Client": ""
      },
      "newUiEnabled": true,
      "classicUiEnabled": true
    },
    {
      "login": "users66",
      "email": "users66@avios.com",
      "name": "users66",
      "city": "Kyiv",
      "cellPhone": "0978535353",
      "phone": "0978535353",
      "cellPhoneEmail": "users66.mobile@avios.com",
      "address": "Zhylyanska",
      "expiredDate": "2019-12-13",
      "systemAccessName": "Basic",
      "active": true,
      "portalPage": "Dashboard",
      "siteSkin": "",
      "userGroupNames": ["Markets", "Hubs", "Carte"],
      "department": "Rad",
      "function": "Clients",
      "country": "United Kingdom",
      "region": "Unilever",
      "subRegion": "Unilever",
      "languageCode": "us",
      "idpId": 3,
      "userExternalId": "users66@avios.com",
      "customFields": {
        "Agency": "",
        "Default client": "Some",
        "User type": "",
        "Organisation type": "",
        "Count": "",
        "Client": ""
      },
      "newUiEnabled": true,
      "classicUiEnabled": true
    }
  ]
}

Notes

  • Each user in the result array corresponds to a row in your import file.

  • If validation fails, an errors array will be included per user entry. Check these to resolve import issues before executing the actual request.

  • Custom fields appear in the customFields object and must use the format FieldName_FieldDefinitionId in the CSV.

4. Execute the Import

Once validation is successful, you can proceed with the import. Only valid records will be processed; any invalid rows will be skipped automatically.

  • Send the CSV to the userBulkSave endpoint.

  • The response will include the system-assigned user IDs for successfully processed rows.

  • Rows containing errors will not be imported and can be retried after resolving the issues.

Example Request

bashCopyEditcurl -X POST \
  -H "Content-Type: application/json" \
  --data-binary @validated-data.json \
  https://.../rest/site/{siteId}/userBulkSave

5. Update Only Specific Fields

When you want to adjust specific user attributes without modifying their other details, include only the necessary columns in your CSV file. Follow this guidance:

  • Provide only the fields you intend to update.

  • Always include an identifier (User id, Login or Email) to target the correct user.

  • If validation issues occur (e.g. “Missing User id”), prepend a comma to your header row.

  • Validate via the preview endpoint before executing the import.

Example CSV

csvCopyEditUser id,Name,New UI Enabled,Default client_5710
26914,John,false,Abbay
36915,Ann,false,Abbay

Example CSV (with comma prefix for validation)

csvCopyEdit,User id,Name,New UI Enabled,Default client_5710
26914,John,false,Abbay
36915,Ann,false,Abbay

Field Validation Rules

Ensure your CSV conforms to the following guidelines to avoid import errors:

Field Type

Validation Requirement

Required for creation

Login, Email, Name (for new users only)

Unique fields

Login, Email, and any configured unique custom fields

Dates

Must use ISO format: YYYY-MM-DD

Email

Must be in a valid format (e.g. name@example.com)

Passwords

Cannot be set via bulk import. Users must reset via “Forgot password”.

Access rights

Must match roles defined in your system configuration

Custom/User-defined fields

Must be specified as FieldName_FieldDefinitionId (e.g. Default client_5710)

List values

Separate multiple entries with semicolons (e.g. Admin;Editor)

Advanced Options

This section offers options to adjust import behaviour across different versions of Encodify:

  • v15.0+ Auto‑fill & Dependencies: Field dependencies are automatically resolved when using v15.0 and above.

  • Legacy mode support: Enable encode.webapp.external-api.legacy-set-fields in YAML to bypass auto‑fill logic and mimic older behaviour.

  • Special characters: Enclose values containing commas, semicolons or other symbols in double quotes.

  • List fields: Use semicolons to present comma-separated data (e.g. Group1;Group2).

Related articles