User Groups API

User Groups API is used for synchronizing groups and their members. Changing group membership can change study tasks because content is often assigned to groups.

What to use it for

Content tends to be assigned to groups, so who sits in which group also decides who studies what. User Groups API keeps that membership in line with your organisational structure.

• A move to another team brings the right training. A warehouse worker transfers to dispatch. Your system removes them from the warehouse group and adds them to the dispatch group by personal_id. Because content is assigned to groups, their study tasks can change with it. Nobody has to work out what they are now missing.
• Groups carry the code from your system. A department is renamed. Your system sets each group’s external_id to the code of the organisational unit and matches on that, not on name. A rename then does not break the synchronisation.
• A whole shift starts at once. Forty people are joining. Your system adds them in batches and verifies the result by listing the group after each batch. Anyone not found among the active users should fail the whole operation, so the integration has a procedure for missing and archived people ready in advance.

Before you send the first batch, read below how the membership endpoints identify people and what happens when one is not found.

Supported tasks

Task	Note
List groups	Returns groups in a company space.
Update group	Can change fields such as external_id, name, or self_assignable.
Add users	Users can be identified by internal IDs, personal_id, or e-mails.
Remove users	Supports the same identifier types as adding users.

User identifiers

Membership endpoints support:

• primary_ids,
• personal_ids,
• emails.

If a user is not found among active users in the company space, the operation should fail. The integration should therefore have a clear process for missing or archived users.

Recommended synchronization model

For periodic synchronization, it is better to send changes in batches and verify the result by listing the group after each batch. Bulk operations can have domain impact on content assignments and reporting.