User bulk import resources

Users can be imported on two different ways. Either via direct API-call with a JSON payload or via a predefined Excel template, which can be uploaded and validated and after successful validation can be imported. Third-party applications will usually use the first option as it is more convenient to use from a technical perspective.

Import via JSON

This request will return immediately while the import is running async in the background.

POST /import/users?mode=import
Parameter Type Default Required Description
mode string import Import mode to use when the users are imported. There are two modes available:
import: For each record in the import file a user is either created if it does not exist or is updated.
sync: User synchronization mode deletes all users that are not in the import file. For all records in the import file the corresponding user is either created, updated or - if deleted - restored.

Json Payload

Parameter Type Default Required Description
firstname string - max. 255 characters.
lastname string - max. 255 characters.
email string - max. 255 characters.
language_id string default network language User interface language ISO 639-1. If not specified, the network default language is used.
gender string u gender code (m = male, f = female, u = unspecified).
country string null Country code in ISO 3166-2 format like CH, DE, US.
location string null Location specific information (department, etc.). Max. 255 characters.
company text null Company of the user. Max. 255 characters.
department text null Department of the user. Max. 255 characters.
position text null Position of the user. Max. 255 characters.
about text null Text to describe the user. This information is showed in the user profile.
employment_start datetime null The employment start date of the user in format yyyy-mm-dd.
auth_type string default Auth Type Specific Auth Type for the user. If not set, the network default Auth Type is selected. List of all Auth Types.
unique_id string - max. 100 characters.
[
    {
      "firstname": "Sherlock",
      "lastname": "Holmes",
      "gender": "m",
      "email": "sherlock.holmes@example.com",
      "auth_type": "simple",
      "language_id": "en",
      "unique_id": "00.42",
      "about": "Detective",
      "location": "London",
      "country": "uk", 
      "company": "Ward, Lock & Co", 
      "department": "Investigations", 
      "position": "Master Detective", 
      "employment_start": "1940-03-10",
      "high_weight_tags": ["Detective"],
      "medium_weight_tags": ["Scotland Yard"],
      "low_weight_tags": ["London"]
    }
]

Response

This request will return immediately while the actual validation is running async in the background.

{
  "import_id": 73,
  "user_id": 17267,
  "file_name": "user_2015-12-11T07:15:50.192Z.json"
}

Upload Excel file

Allows to upload and validate a user bulk import file. No users will be written to the database.

Uploads MUST be performed using the multipart/form-data Content-Type.

Only the Starmind user bulk import excel file is supported.

POST /import/users/upload

This request will return immediately while the actual validation is running async in the background where an import process of "type" validation will be triggered.

Parameter Type Default Required Description
file file The user bulk import file

Response

{
  "import_id": 73,
  "user_id": 17267,
  "file_name": "test_user_starmind.xlsx"
}

If no validation errors occurred, the file is persisted within Starmind (import_id) and ready for being imported.


Import Excel file

PUT /import/users/:ID

Triggers the import of a previously uploaded user bulk import file. :ID correlates with the "import_id" returned from the upload response.

The import will create or update the actual users in the database.

This request will return immediately while the actual import is running async in the background where an import process of "type" import will be triggered.

Response

{
  "import_id": 76,
  "user_id": 17267,
  "file_name": "test_user_starmind.xlsx"
}

Check process status

Since the validation / import is executed async, the process status must be checked before proceeding to the next step. The :ID correlates with the "import_id" returned from the upload / import response.

GET /import/users/:ID/status

Returns the current state of a validation / import process.

The process "status" field can have following values:

"success", "processing", "error"

The process "type" field can have following values:

"validation", "import"

So, per user import two import processes will be created.

Response

Example for successful xlsx import.

{
  "start_date": "2015-12-11T07:15:50.000Z",
  "result": {
    "file_name": "user_2015-12-11T07:15:50.192Z.json",
    "deleted_records": 0,
    "created_records": 1,
    "errors": [],
    "active_user_ids": [
      17350
    ],
    "updated_records": 0,
    "user_id": 17267,
    "restored_records": 0,
    "import_id": 73
  },
  "end_date": "2015-12-11T07:16:08.000Z",
  "status": "success",
  "message": null,
  "import_id": 73,
  "type": "import"
}

Example for a failed xlsx validation.

{
  "start_date": "2015-12-12T07:15:50.000Z",
  "result": {
    "file_name": "user_2015-12-12T07:15:50.192Z.json",
    "deleted_records": 0,
    "created_records": 0,
    "errors": [
        {
          "msg": "must be a valid email address",
          "metadata": null,
          "row": 6,
          "field": "user.email"
        },
        {
          "msg": "Duplicate email address 'sherlock.holmes@example.com' in import file",
          "metadata": "sherlock.holmes@example.com",
          "row": 11,
          "field": "Email"
        },
        {
          "msg": "Duplicate email address 'sherlock.holmes@example.com' in import file",
          "metadata": "sherlock.holmes@example.com",
          "row": 12,
          "field": "Email"
        },
        {
          "msg": "A user 17395 with the email 'sherlock.holmes@example.com' already exists",
          "metadata": "sherlock.holmes@example.com",
          "row": 12,
          "field": "Email"
        }
    ],
    "active_user_ids": [],
    "updated_records": 0,
    "user_id": 17267,
    "restored_records": 0,
    "import_id": 73
  },
  "end_date": "2015-12-12T07:30:08.000Z",
  "status": "error",
  "message": null,
  "import_id": 73,
  "type": "validation"
}

Example for a failed json import.

{
  "start_date": "2015-12-11T07:35:30.000Z",
  "result": {
    "file_name": "user_2015-12-11T07:35:30.612Z.json",
    "deleted_records": 0,
    "created_records": 0,
    "errors": [
      {
        "msg": "Value 'ch' is invalid!",
        "metadata": "firstname.lastname+1@example.com",
        "record": 1,
        "field": "Language"
      }
    ],
    "active_user_ids": [],
    "updated_records": 0,
    "user_id": 17267,
    "restored_records": 0,
    "import_id": 75
  },
  "end_date": "2015-12-11T07:35:30.000Z",
  "status": "error",
  "message": null,
  "import_id": 75,
  "type": "import"
}

List process states

List all user validation / import process states.

GET /import/users/status
[
  {
    "start_date": "2015-12-11T07:35:30.000Z",
    "result": {
      "file_name": "user_2015-12-11T07:35:30.612Z.json",
      "deleted_records": 0,
      "created_records": 0,
      "errors": [
        {
          "msg": "Value 'ch' is invalid!",
          "metadata": "firstname.lastname+1@example.com",
          "record": 1,
          "field": "Language"
        }
      ],
      "active_user_ids": [],
      "updated_records": 0,
      "user_id": 17267,
      "restored_records": 0,
      "import_id": 75
    },
    "end_date": "2015-12-11T07:35:30.000Z",
    "status": "error",
    "message": null,
    "import_id": 75,
    "type": "import"
  },
  {
    "start_date": "2015-12-11T07:15:50.000Z",
    "result": {
      "file_name": "user_2015-12-11T07:15:50.192Z.json",
      "deleted_records": 0,
      "created_records": 1,
      "errors": [],
      "active_user_ids": [
        17350
      ],
      "updated_records": 0,
      "user_id": 17267,
      "restored_records": 0,
      "import_id": 73
    },
    "end_date": "2015-12-11T07:16:08.000Z",
    "status": "success",
    "message": null,
    "import_id": 73,
    "type": "import"
  }
]