The Reporting API supplies a number of HTTP endpoints that expose ways to export data from users, groups, activities, journeys, programmes, skills and training times. The target audience of this document are developers who will be implementing an API connection for extracting data from the TinQwise learning platform for reporting purposes.

To explore the available endpoints use the interactive documentation. It can be accessed at https://<platform name>.platform.co.nl/api/v2/public/docs/. Here is a quick example to look at https://tinqwise.platform.co.nl/api/v2/public/docs/)

To connect with the reporting API in a secure way we support OAuth2 with the Client Credentials Grant flow.

A client_id, client_secret and scope are needed to request an access token that can be used for authentication. Contact the Service Desk if you need a client_id and client_secret and specify which scopes you require.

Using your client_id and client_secret request an authorization token using the Token URL. Click the Authorize button in your interactive documentation to see your token URL. This token is necessary when you send a request to our API. Please note that the scope for which the token is provided should match the scope for the API which you are trying to use. Keep in mind that tokens are only active for a limited amount of time.

There is only one scope for each endpoint, which is the 'read' scope required for GET requests.

The available scopes are:

List users using the /api/v2/reports/users/ GET endpoint. You can filter on specific users by id in the /api/v2/reports/users/{id}. You can use a number of filters to find users within a certain timeframe based on contract_start_date, contract_end_date, last_seen, registration_date , filter on a specific user by email, uuid or employee_id, or filter on certain groups by group_name.

id users are uniquely identified by their id, and all other endpoints in API v2 that refer to users through this identifier referred to as user_id.

uuid users are uniquely identifier by an automatically generated code when user was created
​username the username of a user.

email the unique email address of a user.

first_name and last_name are used to refer to a user on the platform.
​registration_date the date a user registered on the platform.
​last_seen the date of the last login of the user on the platform.

contract_start_date and contract_end_date the dates of a user's start and end of their contract. Optional data.
​flexible_field can be any user profile field that is custom made on your platform.

status if a user is active, pending or suspended on the platform.

employee_id is a customer-specific (unique) identifier, which can be used to disambiguate users.

saml_username is the username used with a saml2 SSO.

Use the GET /api/v2/reports/groups/ endpoint to retrieve a list of groups. You can filter on specific groups by id in the /api/v2/reports/groups/{id}. In other endpoints you can use the group_name to filter on specific groups.

name is the unique identifier for this group.

type is the grouptype of this group.

name_i18n is the internationalized (i18n) or translated name for this group.

parent_name is the name of the parent of this group. Matches the name field of the parent group.

external_name the optional id or name which the group is known by the customer.
​created_by_user_importer is optional and set on 'true' when created by a user provisioning integration for importing users and groups.

extra a JSON dictionary containing the information within the custom group fields of the platform.

Use the GET api/v2/reports/modules/ to retrieve data on the progress of activities in the platform. You can filter on specific activities by id in the /api/v2/reports/modules/{id}. You can filter activities within a certain timeframe on completed_at, expires_at, failed_at, modified_at, started_at or filter on certain groups by group_name.

id is the unique identifier of an activity invite in combination with a specific user.

user_id matches the user ‘id’ field in our Users API.

module_uuid is the unique identifier of an activity.

module_name the name of the activity.

module_identifier the internal label of an activity.

module_type type of activity like learning-bite, exam, session, etc.

module_duration theoretical duration of the activity.

progress percentage between 0-100% indicating how far along the user is with the specific activity.

started_at datetime stamp from moment activity was started by user.

completed_at datetime stamp from moment activity was completed by user.

expires_at datetime stamp with moment activity will expire in the future.

expired_at datetime stamp with moment activity has expired in the past.

graded_at datetime stamp when activity was graded by manager/teacher.

failed_at datetime stamp with moment activity was failed.

modified_at datetime stamp when this activity was last updated.

is_completed default on 'false' – but set on 'true' if activity is completed

grade the grade of an activity (like good/excellent etc.).

score the score of an activity (like 5/6 questions right).

optional default on 'false' – but set on 'true' if activity is optional content.

attempt number of the current attempt of the activity.

accreditation_points number of the accredited points for the activity.

Use the GET api/v2/reports/journeys/ to retrieve data on the progress of journeys in the platform. You can filter on specific journeys by id in the /api/v2/reports/journeys/{id}. You can filter journeys within a certain timeframe on created_at, modified_at and completed_at or or filter on certain groups by group_name.
​

id is the unique identifier of the journey in combination with a specific user.
​user_id matches the user ‘id’ field in our Users API.

journey_uuid the unique identifier of the journey. When the result is a section, this field contains the uuid of the journey the section is part of.

journey_name the name of the journey. When the result is a section, this field contains the name of the journey the section is part of.

section_uuid the unique identifier of the section. This fields is empty when the result is a journey.

section_name the name of the section. This fields is empty when the result is a journey.

progress percentage between 0-100% indicating how far along the user is with the specific journey or section.

created_at datetime stamp from moment journey was created.

modified_at datetime stamp when this journey was last updated.

completed_at datetime stamp from moment journey was completed by user.

Use the GET api/v2/reports/programmes/ to retrieve data on the progress of programmes in the platform. You can filter on specific programmes by id in the /api/v2/reports/programmes/{id}. You can filter programmes within a certain timeframe on completed_at or on programme id's.
​
​programme_uuid the unique identifier of the programme.

programme_title the name of the programme.
​user_id matches the user ‘id’ field in our Users API.

progress percentage between 0-100% indicating how far along the user is with the specific programme.

completed_at datetime stamp from moment programme was completed by user.

Use the GET api/v2/reports/skills/ to retrieve data on the progress of skills and badges users are working on in the platform. You can filter on specific skills by id in the /api/v2/reports/skills/{id}. You can filter skills within a certain timeframe on completed_at, expires_at, failed_at, modified_at or filter on certain skill or user id's.

id is the unique identifier of the badge in combination with a specific user.
​user_id matches the user ‘id’ field in our Users API.

skill_uuid the unique identifier of the skill the badge represents.

skill_name the name of the skill the badge represents.

progress percentage between 0-100% indicating how far along the user is with the specific journey or section.

seen_at datetime stamp from moment the user saw the badge.

flagged default on 'false' – but set on 'true' if user flagged the skill as they don't master this skill anymore.

expires_at datetime stamp with moment badge will expire in the future.

completed_at datetime stamp from moment badge was completed by user.

last_nudged_at datetime stamp from moment a manager nudged the skill for a user to complete it.
​modified_at datetime stamp when this skill was last updated.

Use the GET api/v2/reports/training_time/ to retrieve data on the time spend on (completed) activities in the platform. You can filter on specific user_id's in the /api/v2/reports/training_time/{user_id}. You can filter activities counting towards the training time must have been completed within a certain timeframe on reporting_period_start and reporting_period_end or filter on certain users or groups by user_id or group_name.
​
​user_id matches the user ‘id’ field in our Users API.

total_training_time: number of minutes the user has spend on activities on our platform (based on the duration of completed activities).
When the Training Type Feature is enabled on the platform this API also returns:

informal_training_time: number of minutes the user has spent on informal activities.

formal_training_time: number of minutes the user has spent on formal activities.

The IDs returned for activity, journey or skill/badge are unique for the attempt. For example, when the activity is reset, the API will return a new id.
​