User synchronization

This section covers the topic of creating, editing, and deleting users

General​

The userId is the unique identifier for a user, used to access that user. When creating a user through the web interface, the userId is always the same as the email. However, when creating a user via the API, you are free to choose the userId.

User Lifecycle

Create User​

To create one or more users, we use the ‚user_bulk‘ endpoint:

POST api.int-tutool.io/lms/tenant/users-bulk

json body:

{
    "items": [
        {
            "userId": "tutoolio.test@tutool.io",
            "subject": "",
            "title": "",
            "firstname": "tutoolio",
            "lastname": "test0",
            "email": "tutoolio.test@tutool.io",
            "tags": ["gruppe1", "gruppe2"]
        }
    ]
}
curl --location 'https://api.int-tutool.io/lms/tenant/users-bulk' \
--header 'x-tenant-id: <insert-tenant-id>' \
--header 'x-instance-id: <insert-instance-id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <insert-token>' \
--data-raw '{
    "items": [
        {
            "userId": "tutoolio.test@tutool.io",
            "subject": "",
            "title": "",
            "firstname": "tutoolio",
            "lastname": "test0",
            "email": "tutoolio.test@pkd.de",
            "tags": ["gruppe1", "gruppe2"]
        }
    ]
}'

The subject id refers to the ID that the user receives in your identity provider. If you are unsure how to obtain this ID, you can also leave it empty. Our system will automatically populate it when the user logs in.

Update User​

At the moment, users can only be updated individually.

PUT api.int-tutool.io/lms/tenant/users/[userId]

json body:

{
    "userId": "tutoolio.test@tutool.io",
    "subject": "",
    "title": "Mr",
    "firstname": "magier",
    "lastname": "test0",
    "email": "tutoolio.test@tutool.io"
}
curl --location --request PUT 'https://api.int-tutool.io/lms/tenant/users/tutoolio.test@tutool.io' \
--header 'x-tenant-id: <insert-tenant-id>' \
--header 'x-instance-id: <insert-instance-id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: <insert-bearer-token>' \
--data-raw '{
"userId": "tutoolio.test@pkd.de",
"subject": "00u3mmcgrnMhIZVsG0i7",
"title": "Mr",
"firstname": "magier",
"lastname": "test0",
"email": "tutoolio.test@pkd.de"
}'

Update user tags​

There is a separate endpoint available for updating user tags. Please note that all existing tags will be replaced with the tags provided in this update. If you wish to delete a user’s tags, you would send an empty array.

json body:

{
  "tags": [
    "tag-1", "tag-2"
  ]
}
curl --location --request PUT 'https://api.int-tutool.io/lms/tenant/users/tutoolio.test@tutool.io/tags' \
--header 'x-tenant-id: <insert-tenant-id>' \
--header 'x-instance-id: <insert-instance-id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <insert-bearer-token>' \
--data '{
  "tags": [
    "tag-1", "tag-2"
  ]
}'

Deactivate user​

Deactivated users can no longer log in to our system, but all information regarding courses and certificates is retained. Only when a user is deleted are all user-related details irreversibly removed.

To deactivate one or more users, you can also use the Bulk User endpoint here. Only active users can be deactivated. If you attempt to deactivate a user who is already deactivated, you will receive the HTTP Statuscode 404.

The userId or multiple user IDs are passed in the items array.

json body:

{
  "items": ["tutoolio.test@tutool.io"]
}
curl --location --request PUT 'https://api.int-tutool.io/lms/tenant/users-bulk/suspend' \
--header 'x-tenant-id: <insert-tenant-id>' \
--header 'x-instance-id: <insert-instance-id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <insert-bearer-token>' \
--data-raw '{
  "items": ["tutoolio.test@tutool.io"]
}'

Activate User​

Once a user is reactivated, they regain access to all their courses and certificates.

Only deactivated users can be reactivated here. If the user is not deactivated or has already been deleted, the HTTP status code 404 will be returned.

PUT api.int-tutool.io/lms/tenant/users-bulk/activate
{
  "items": ["tutoolio.test@tutool.io"]
}
curl --location --request PUT 'https://api.int-tutool.io/lms/tenant/users-bulk/activate' \
--header 'x-tenant-id: <insert-instance-id>' \
--header 'x-instance-id: <insert-instance-id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <insert-instance-id>' \
--data-raw '{
  "items": ["tutoolio.test@tutoo.io"]
}'

Delete User​

Please note that only deactivated users can be deleted. If you want to delete an active user, they must first be deactivated and can then be deleted. All information about a user is irreversibly deleted, including certificates and course progress. In course reports (such as the number of completions in a specific period), users will still appear as entities but without a connection to the real person. The person will then be listed as ‚firstname: DELETED, lastname: DELETED, email: DELETED.DELETE api.int-tutool.io/lms/tenant/users-bulk

api.int-tutool.io/lms/tenant/users-bulk

json body:

{
  "items": ["tutoolio.test@tutool.io"]
}
curl --location --request DELETE 'https://api.int-tutool.io/lms/tenant/users-bulk' \
--header 'x-tenant-id: <insert-tenant-id>' \
--header 'x-instance-id: <insert-instance-id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: <insert-bearer-token>' \
--data-raw '{
  "items": ["tutoolio.test@tutool.io"]
}'

Get users​

To modify a user, we need the user_id. When creating users through the API, you have the flexibility to choose the user ID. If the user is created through the web interface, the user ID will be the email address.

If you don’t know the user_id of a user or want to query all users once to compare them with your system, you can use the following endpoint.

GET api.int-tutool.io/lms/tenant/users
curl --location 'https://api.int-tutool.io/lms/tenant/users' \
--header 'x-tenant-id: <insert-tenant-id>' \
--header 'x-instance-id: <insert-instance-id>' \
--header 'Authorization: Bearer eyJh...' \
--data ''

Example Response

{
  "content": [
    {
      "userId": 4711, <-- userId
      "loginId": "user@login.id",
      "subject": "5fda9bc9-4a31-41ee-a93d-22d9c35765bc",
      "title": "Mr.",
      "firstname": "John",
      "lastname": "Doe",
      "email": "user@domain.tld",
      "state": "ACTIVE",
      "tags": [
        "tag1"
      ],
      "roles": [
        "LEARNER"
      ],
      "attributes": []
    }
  ],
  "page": {
    "size": 0,
    "totalElements": 0,
    "totalPages": 0,
    "number": 0
  }
}

If you want to filter for a specific user, you can provide this filter as a query parameter to filter by email:

Query Parameter: filterParameter

{
    "dtype":
    "FilterComposition",
    "condition":"AND",
    "filters":
        [
            {
                "dtype":"FilterLike",
                "key":"email",
                "value":"<insert-email>"
            }
        ]
}
curl --location 'https://api.int-tutool.io/lms/tenant/users?size=2000&page=0&filterParameter=%7B%22dtype%22%3A%22FilterComposition%22%2C%22condition%22%3A%22AND%22%2C%22filters%22%3A%5B%7B%22dtype%22%3A%22FilterLike%22%2C%22key%22%3A%22email%22%2C%22value%22%3A%22test%40tutool.io%22%7D%5D%7D' \
--header 'x-tenant-id:  <insert-tenant-id>' \
--header 'x-instance-id: <insert-instance-id>' \
--header 'Authorization: Bearer eyJhb...'

Get user

GET api.int-tutool.io/lms/tenant/users/[userId]
curl --location 'https://api.int-tutool.io/lms/tenant/users/tutoolio.test@tutool.io' \
--header 'x-tenant-id: <insert-tenant-id>' \
--header 'x-instance-id: <insert-instance-id>' \
--header 'Authorization: Bearer eyJh...'