Skip to main content

Groups and group types via the API

Retrieve, create, modify and structure groups with Web API v3

Written by TinQwise Service

Groups are the main method in the TinQwise learning platform to provide content differentiation and control permissions, see How to create and manage groups in Control.

The group structure is hierarchical. Most groups are subgroups of a parent group.

Part of Web API v3 for user management. You need a token with the v3:groups:read or v3:groups:write scope, see Authenticating with the Web API v3.

Group types

Group types are used to display group selectors in the frontend and have some configuration options.

Some group types are created by the system, such as vouchers, Remote Scorm, Admin groups and Programme group.

🚧 Be careful

Group types should be used sparingly. Even big platforms have maybe ten different group types, not hundreds.

👀 Good to know

It is currently not possible to manage group type details through the API, such as whether a group type shows in profiles and can be selected in a report. For more on group types, see All about group types.

Structuring your groups

It is good practice to give most groups a parent group with type sorting, which acts as a top-level group. For example:

  • Countries (type: sorting, parent: null)

    • Netherlands (type: country, parent: Countries)

      • Hilversum (type: city, parent: Netherlands)

      • Amsterdam (type: city, parent: Netherlands)

    • Belgium (type: country, parent: Countries)

      • Antwerp (type: city, parent: Belgium)

  • Vouchers (type: sorting, parent: null)

    • abcdef (type: voucher, parent: Vouchers)

Retrieving groups

Use the GET /api/v3/public/groups/ endpoint to retrieve a list of groups. You can filter on parent_uuid, group_type, external_id and identifier, for example /api/v3/public/groups/?external_id=WD-12345.

Field

Description

uuid

The unique identifier for this group.

identifier

A legacy internal name, for example 576-270-analyst intern. Read-only. It is often based on the group's name, so do not use it to match groups with your own system; use external_id instead.

group_type

The group type of this group.

name_i18n

The internationalized (i18n) or translated name for this group. A JSON object with keys corresponding to language codes (ISO 639-1) and values corresponding to localized names of this group. A translation should be provided for all supported languages on the platform. Example: {"en": "Group Name", "nl": "Groepsnaam"}

parent_uuid

The uuid of the parent of this group.

external_id

Your own identifier for this group, such as the reference ID from your HR system. Your integration sets and maintains it.

Matching groups with your own system

Use external_id to link a group to the matching record in your HR system. It stays the same when a group is renamed, unlike identifier and the group's name.

  • For groups your integration creates, set external_id in the POST request.

  • For groups that already exist on the platform, set external_id once with a PATCH request to /api/v3/public/groups/{uuid}/. The group keeps its uuid and its members.

  • From then on, find a group with ?external_id=.

Creating and modifying groups

POST to /api/v3/public/groups/ creates a new group.

PUT or PATCH to /api/v3/public/groups/{uuid}/ will modify an existing group. The PUT requires all writable fields to be included, while the PATCH only updates provided fields.

Deleting groups

It is not possible to delete a group which is still referenced in an automation, or which is used for internal purposes such as a Programme group.

Next: Group memberships via the API to add users to the groups you created.

Did this answer your question?