User Learning Status Extraction API

Purpose

Cyber Guru provides the ability to retrieve users' learning status for assigned content through a REST API that returns data in JSON format, ready to be integrated into external reporting systems (e.g., Docebo or the customer's LMS platforms).
The API provides a unified list of users with their respective learning status, an aggregated summary by status, and pagination support for handling large datasets.
This guideline contains the instructions and parameters for invoking the service.

Scope

This information applies to the Cyber Security Awareness Cyber Guru 2.0 platform.

Prerequisites

• The customer must have the technical resources to call REST APIs.

Procedure

Cyber Guru provides two REST APIs:

Get token:

URL: https://login.platform.cyberguru.eu/realms/{TENANT}/protocol/openid-connect/token

This API allows you to obtain an authorization token. Call parameters (POST method):

• client_id : ext-api
• client_secret : (provided by Cyber Guru)
• grant_type : client_credentials

Get users learning status:

URL: https://<host>/ext/report/users-learning-status

This API allows you to retrieve the list of users with their learning status. To call the API, you must provide the previously obtained token as a Bearer token.
The API accepts the following parameters (GET method):

User status mapping

Response examples

Basic response (without pagination):

{
  "users": [
    { "firstname": "Anna", "lastname": "Ferrari", "email": "anna.ferrari@company.com", "team": "Finance", "status": "aligned" },
    { "firstname": "Marco", "lastname": "Rossi", "email": "marco.rossi@company.com", "team": "IT Operations", "status": "regular" },
    { "firstname": "Luigi", "lastname": "Bianchi", "email": "luigi.bianchi@company.com", "team": "Sales EMEA", "status": "not-active" }
  ],
  "total_users": 3,
  "summary": {
    "not-active": 1,
    "not-regular": 0,
    "regular": 1,
    "aligned": 1
  }
}

Response with pagination:

{
  "users": [
    { "firstname": "Anna", "lastname": "Ferrari", "email": "anna.ferrari@company.com", "team": "Finance", "status": "aligned" },
    { "firstname": "Marco", "lastname": "Rossi", "email": "marco.rossi@company.com", "team": "IT Operations", "status": "regular" }
  ],
  "total_users": 150,
  "summary": { "not-active": 10, "not-regular": 30, "regular": 50, "aligned": 60 },
  "pagination": {
    "current_page": 1, "per_page": 10, "total_items": 150, "total_pages": 15,
    "from": 1, "to": 10, "has_next": true, "has_prev": false,
    "next_page": 2, "prev_page": null, "first_page": 1, "last_page": 15
  }
}

When the status filter is applied, the summary field only shows the count for the filtered status.

Response with status filter (e.g., status=0):

{
  "users": [
    { "firstname": "Luigi", "lastname": "Bianchi", "email": "luigi.bianchi@company.com", "team": "Sales EMEA", "status": "not-active" }
  ],
  "total_users": 1,
  "summary": { "not-active": 1 }
}

The fields in the pagination object have the same meaning as described for other APIs in the Rankings service.

Errors

Technical notes

• For datasets with more than 1000 users, it is recommended to always use the limit and page parameters to avoid timeouts.
• The value of limit should be chosen based on the size of the company's user population registered on the platform.

Cyber Guru is available to support customers during the configuration and testing phase in the staging environment and, after successful testing, in the production environment.