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

All these API endpoints have been deprecated by version 2.122.0 in favour of the new Accounts GraphQL API.

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.

[
    {
      "firstname": "Sherlock",
      "lastname": "Holmes",
      "gender": "m",
      "email": "sherlock.holmes@example.com",
      "auth_type": "simple",
      "language_id": "en",
      "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

All these API endpoints have been deprecated by version 2.122.0 in favour of the new Accounts GraphQL API.

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

All these API endpoints have been deprecated by version 2.122.0 in favour of the new Accounts GraphQL API.

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

All these API endpoints have been deprecated by version 2.122.0 in favour of the new Accounts GraphQL API.

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"
  }
]