The sync endpoint lets you synchronize users in bulk, instead of making multiple individual requests. You send a list of users along with a configuration object and the endpoint automatically creates, updates, activates or deactivates users as needed.

In addition to users, the sync endpoint can also create objects that is part of the user objects, the departments, job profile and permissions. They will be created if they are referenced in the user data and allowed by the configuration.

Note on request size

The endpoint does not currently enforce a maximum number of users per request. However, if more than 2000 users are send in one request, the request may time out. In such cases, the sync process will continue running on our servers, but the request itself will return no response.

Automatic User Creation or Update

By sending the entire list of users, the sync endpoint will automatically detect whether users should be created, updated, activated or deactivated in the Learningbank platform. What the integration updates, depends on the config object.

Identification

The endpoint identifies existing users by checking the following attributes in order:

1. External ID
2. Email
3. Username
4. Phone number*

If no existing user has values in these attributes that equals to the values of a user in the user array, the user is regarded as a new user.

*: Phone number is only checked against users on the platform, that only has a phone number. If two users therefore has the same number, but they also have an email that is different, two different users will be created.

Automatic Creation of Objects

Depending on the config, the sync endpoint can also automatically create related objects referenced by users, such as:

• Departments
• Job Profiles
• Permissions

Note: Objects are only created if they do not exist. Existing objects will not be updated.

Disclaimer: No Department Hierarchy

Departments created via the sync endpoint are always added in a flat hierarchy. To set up parent-child relations, you must either configure them manually in the platform or use the dedicated department endpoints.

Config Object

Together with the array of user objects, it is also possible to send a config object. The config object allows for changing the way the sync endpoint works, by for example dictating whether or not objects should be created, if certain attributes should not be overwritten, etc. For further explanation on the config, please read the config part of the request body below.

Returned Object

The returned object shows 6 different attributes: created, updated, activated, deactivated, skipped and errors. The 5 first gives back the number of users, who got that action type. The errors however is an array of strings, that explains the individual errors with users, that made the endpoint not handle them. For the first 5, this is the explanation for each of them:

• created: How many new users were created on the platform. This means, that the user did not exist beforehand, not even in a deactivated state.
• updated: How many users, who already existed on the platform, were updated in any way. This also counts, if a user gets deactivated or activated, then they are both updated, but they will also count in the activated and deactivated array. 
• activated: How many users, who were deactivated on the platform, has now been activated.
• deactivated: How many users, who were activated on the platform, has now been deactivated.
• skipped: Users are skipped two ways. The first one being, if a user currently does not exist on the platform, but their isActive property is false in the request. We do this, as we do not want to create a user, who is deactivated. The second way is, if a user is missing the three fields: email, phone or username. If all three are empty, a user is skipped.

Note: If a user is sent, that already exist and with nothing to update, the integration skips them. They are not added to any of the counts of the actions, meaning the total amount of actions in the response, might vary from the actual amount sent.