Skip to content

API: Organizations endpoints

/organizations

GET /organizations

List owned and managed organizations.

[] Input:

  • string search: optional search string to filter results
  • integer limit: limit number of results
    • default: 16
  • integer page: page number
    • default: 1
    • not used in search mode!

[] Output:

  • list organizations
    • string organization: organization identification string
    • string/null id: external unique organization identifier (if set for the organization)
    • string title: title of the organization

/organization

GET /organization

Get/check organization.

[] Input:

  • [!] string organization: organization identification string

[] Output:

  • string organization: organization identification string
  • string/null id: external unique organization identifier (if set for the organization)
  • string title: title of the organization
  • string description: short description of the organization (only present if set for the organization)

POST /organization

Create an organization.

[] Input:

  • [!] string title: title of the organization
  • string description: optional short description
  • string domain: domain name (FQDN) for the organization without www prefix
    • needs special privileges to set!
  • string[url] website: homepage URL
  • string[email] email: contact email address
  • string[phone] phone: contact phone number
  • string custom_{field}: custom field data (only if specified field is configured for target EduBase instance)

[] Output:

  • string organization: organization identification string

PATCH /organization

Update organization.

[] Input:

  • [!] string organization: organization identification string
  • string{1,255} title: title of the organization
  • string custom_{field}: custom field data (only if specified field is configured for target EduBase instance)

DELETE /organization

Remove organization.

[] Input:

  • [!] string organization: organization identification string

/organization:members

GET /organization:members

List all members in a organization.

[] Input:

  • [!] string organization: organization identification string

[] Output:

  • list members
    • string user: user identification string
    • string name: name of the member
    • string/null department: name of the department (if member)
    • hash permission
      • string organization: permission level to organization
      • string content: permission level to contents in organization
      • string members: permission level to members in organization

POST /organization:members

Assign user(s) to a organization. Updates memberships if already member of the organization.

[] Input:

  • [!] string organization: organization identification string
  • [!] string users: comma-separated list of user identification strings
  • string department: optional name of department
    • department and permission_ fields should not be used together
    • the competency assignments of the members moved to another department are updated, the competencies they only had through their previous department are lost
  • string permission_organization: optional permission level to organization
    • possible values: member / teacher / reporter / supervisor / admin
    • default: member
  • string permission_content: optional permission level to contents in organization
    • possible values: none / view / report / control / modify / grant / admin
    • default: none
  • string permission_members: optional permission level to members in organization
    • possible values: none / department / organization
    • default: none
  • boolean notify: notify users
    • default: false

DELETE /organization:members

Remove user(s) from a organization.

[] Input:

  • [!] string organization: organization identification string
  • [!] string users: comma-separated list of user identification strings

/organizations:members

POST /organizations:members

Assign user(s) to organization(s). Updates memberships if already member of a organization.

[] Input:

  • [!] string organizations: comma-separated list of organization identification strings
  • [!] string users: comma-separated list of user identification strings
  • string department: optional name of department
    • if department is not found in an organization, permission_ fields are used to set permission levels
    • the competency assignments of the members moved to another department are updated, the competencies they only had through their previous department are lost
  • string permission_organization: optional permission level to organization
    • possible values: member / teacher / reporter / supervisor / admin
    • default: member
  • string permission_content: optional permission level to contents in organization
    • possible values: none / view / report / control / modify / grant / admin
    • default: none
  • string permission_members: optional permission level to members in organization
    • possible values: none / department / organization
    • default: none
  • boolean notify: notify users
    • default: false

/organization:departments

GET /organization:departments

List all departments of an organization, ordered by their hierarchy.

[] Input:

  • [!] string organization: organization identification string

[] Output:

  • string organization: organization identification string
  • list departments
    • string department: name of the department
    • string/null id: external unique department identifier (if set for the department)
    • string/null parent: name of the parent department (if set)
    • integer level: depth of the department within the hierarchy (0 for root level departments)
    • hash permission
      • string organization: permission level to organization given to the members
      • string content: permission level to contents in organization given to the members
      • string members: permission level to members in organization given to the members
    • integer members: number of visible members in the department
    • list leaders
      • string user: user identification string
      • string name: name of the leader

/organization:department

GET /organization:department

Get a department of an organization.

[] Input:

  • [!] string organization: organization identification string
  • [!] string department: name of the department
    • the external identifier of the department can also be used

[] Output:

  • string organization: organization identification string
  • string department: name of the department
  • string/null id: external unique department identifier (if set for the department)
  • string/null parent: name of the parent department (null for root level departments)
  • integer level: depth of the department within the hierarchy (0 for root level departments)
  • hash permission
    • string organization: permission level to organization given to the members
    • string content: permission level to contents in organization given to the members
    • string members: permission level to members in organization given to the members
  • integer members: number of visible members in the department
  • list leaders
    • string user: user identification string
    • string name: name of the leader

POST /organization:department

Create a department in an organization.

[] Input:

  • [!] string organization: organization identification string
  • [!] string{1,255} title: name of the department
    • must be unique within the organization
  • string{0,64} id: external unique department identifier
  • string parent: name or external identifier of the parent department
    • default: the department is created on root level
  • string permission_organization: permission level to organization given to the members
    • possible values: member / teacher / reporter / supervisor / admin
    • default: member
  • string permission_content: permission level to contents in organization given to the members
    • possible values: none / view / report / control / modify / grant / admin
    • default: none
  • string permission_members: permission level to members in organization given to the members
    • possible values: none / department / organization
    • default: none
  • string leaders: comma-separated list of user identification strings
    • leaders must be members of the organization
    • at most 5 leaders can be specified

[] Output:

  • string organization: organization identification string
  • string department: name of the department
  • string/null id: external unique department identifier (if set for the department)

PATCH /organization:department

Update a department of an organization. Only the specified fields are changed. When the permission levels are changed, they are applied automatically.

[] Input:

  • [!] string organization: organization identification string
  • [!] string department: name or external identifier of the department
  • string{1,255} title: new name of the department
    • must be unique within the organization
  • string{0,64} id: external unique department identifier
    • an empty value removes the identifier
  • string parent: name or external identifier of the parent department
    • an empty value moves the department to the root level
    • the department itself or a department below it cannot be the parent
  • string permission_organization: permission level to organization given to the members
    • possible values: member / teacher / reporter / supervisor / admin
  • string permission_content: permission level to contents in organization given to the members
    • possible values: none / view / report / control / modify / grant / admin
  • string permission_members: permission level to members in organization given to the members
    • possible values: none / department / organization
  • string leaders: comma-separated list of user identification strings
    • replaces the current leaders, an empty value removes every leader
    • leaders must be members of the organization
    • at most 5 leaders can be specified

DELETE /organization:department

Remove a department from an organization. The members of the department are left without a department and lose the permission levels and competency assignments given by it, the departments below it are moved one level up.

[] Input:

  • [!] string organization: organization identification string
  • [!] string department: name or external identifier of the department

/organization:competencies

GET /organization:competencies

List all competencies of an organization. Library and competencies must be enabled for the organization.

[] Input:

  • [!] string organization: organization identification string

[] Output:

  • string organization: organization identification string
  • list competencies
    • string competency: competency identification string
    • string/null id: external unique competency identifier (if set for the competency)
    • string title: title of the competency
    • string/null description: description of the competency (if set)
    • integer requirements: number of requirements
    • integer documents: number of library documents attached
    • hash assignments
      • boolean all: assigned to every member of the organization
      • integer departments: number of departments assigned to
      • integer members: number of members assigned to individually
    • integer assigned: number of visible members assigned to the competency
    • hash status: number of assigned members by their competency status
      • integer completed: completed
      • integer progress: in progress
      • integer waiting: waiting for completion
      • integer expired: expired
      • integer due: due soon
      • integer overdue: past the deadline
      • integer outdated: outdated

/organization:competency:requirements

GET /organization:competency:requirements

List the requirements of a competency. Library and competencies must be enabled for the organization of the competency.

[] Input:

  • [!] string competency: competency identification string
    • the external identifier of the competency can also be used when organization is specified
  • string organization: organization identification string

[] Output:

  • string organization: organization identification string
  • string competency: competency identification string
  • string/null id: external unique competency identifier (if set for the competency)
  • string title: title of the competency
  • list requirements: requirements ordered by their priority
    • string requirement: requirement identification string
    • string/null title: title of the requirement
    • string type: type of the requirement
      • possible values: exam / class / document / journey / todo
    • boolean optional: requirement is optional
    • string description: description of the requirement (only present if set for the requirement)
    • hash deadline: deadline of the requirement (only present if a deadline is configured)
      • string type: type of the deadline
        • possible values: date / days
      • date date: fixed deadline (only if type is date)
      • integer days: number of days available to complete the requirement (only if type is days)
    • hash/null exam: the required exam (only present if type is exam, null if the exam is not available)
      • string exam: exam identification string
      • string/null id: external unique exam identifier (if set for the exam)
      • string title: title of the exam
    • hash/null class: the required class (only present if type is class, null if the class is not available)
      • string class: class identification string
      • string/null id: external unique class identifier (if set for the class)
      • string title: title of the class
    • hash/null document: the required library document (only present if type is document, null if the document is not available)
      • string document: document identification string
      • string/null prefix: prefix of the document
      • string title: title of the document
      • boolean archived: document is archived
    • hash/null journey: the required exam journey (only present if type is journey, null if the journey is not available)
      • string exam: exam identification string of the starting exam (see GET /exam:journey)
      • string title: title of the journey
      • boolean active: the journey is enabled
      • list{string} outcomes: outcomes the journey has to be finished with to fulfill the requirement (empty if any outcome is accepted)
    • hash todo: the required task (only present if type is todo)
      • string type: type of the task
        • possible values: default / document / exam / training
      • boolean attachments: attachments can be uploaded
      • list educators: educators of the training (only present if type is training, visible users only)
        • string user: user identification string
        • string name: name of the educator
      • list{string} fields: labels of the fields to fill (only present if type is not default)
    • list{string} documents: identification strings of the library documents attached to the requirement (only present if there are any)

/organization:compliance

GET /organization:compliance

Get the competency compliance overview of an organization, grouped by departments. Organization reporters see every visible member, department leaders only the members of the departments they lead. Library and competencies must be enabled for the organization.

[] Input:

  • [!] string organization: organization identification string

[] Output:

  • string organization: organization identification string
  • string scope: scope of the overview
    • possible values: organization (whole organization) / departments (only the departments led by the user)
  • list competencies: competencies with any assigned member within the scope
    • string competency: competency identification string
    • string/null id: external unique competency identifier (if set for the competency)
    • string title: title of the competency
  • list departments: departments with any member or progress within the scope, ordered by their hierarchy
    • string/null department: name of the department (null for the members without a department, in organization scope only)
    • string/null id: external unique department identifier (if set for the department)
    • string/null parent: name of the parent department (null for root level departments)
    • integer level: depth of the department within the hierarchy (0 for root level departments)
    • integer members: number of members in the department
    • list competencies: competency statistics of the department (only competencies with assigned members are listed)
      • string competency: competency identification string
      • integer assigned: number of members assigned to the competency
      • hash status: number of assigned members by their competency status (same keys as the top level status)
  • integer assigned: total number of competency assignments within the scope
  • hash status: total number of competency assignments by their status
    • integer completed: completed
    • integer progress: in progress
    • integer waiting: waiting for completion
    • integer expired: expired
    • integer due: due soon
    • integer overdue: past the deadline
    • integer outdated: outdated

/user:organizations

GET /user:organizations

List all organizations a user is member of.

[] Input:

  • [!] string user: user identification string

[] Output:

  • list organizations
    • string organization: organization identification string
    • string/null id: external unique organization identifier (if set for the organization)
    • string title: title of the organization
    • string link: link to the organization manager page
    • string/null department: name of the department (if member)
    • hash permission
      • string organization: permission level to organization
      • string content: permission level to contents in organization
      • string members: permission level to members in organization

POST /user:organizations

Assign user to organization(s). Updates membership if already member of a organization.

[] Input:

  • [!] string user: user identification string
  • [!] string organizations: comma-separated list of organization identification strings
  • string department: optional name of department
    • if department is not found in an organization, permission_ fields are used to set permission levels
    • the competency assignments of the members moved to another department are updated, the competencies they only had through their previous department are lost
  • string permission_organization: optional permission level to organization
    • possible values: member / teacher / reporter / supervisor / admin
    • default: member
  • string permission_content: optional permission level to contents in organization
    • possible values: none / view / report / control / modify / grant / admin
    • default: none
  • string permission_members: optional permission level to members in organization
    • possible values: none / department / organization
    • default: none
  • boolean notify: notify user
    • default: false

DELETE /user:organizations

Remove user from organization(s).

[] Input:

  • [!] string user: user identification string
  • [!] string organizations: comma-separated list of organization identification strings

/organization:webhook

GET /organization:webhook

Get/check webhook configured in organization.

[] Input:

  • [!] string organization: organization identification string
  • [!] string webhook: webhook identification string

[] Output:

  • string organization: organization identification string
  • string webhook: webhook identification string
  • string title: title of the webhook
  • boolean active: webhook is active

POST /organization:webhook

Create a webhook for an organization.

[] Input:

  • [!] string organization: organization identification string
  • [!] string title: title of the webhook
  • [!] string trigger_event: type of event to trigger webhook
    • possible values: exam-play-result / quiz-play-result / journey-completed / api
      • exam-play-result: triggers when a user (must be member of the organization) completes an exam in the organization
      • quiz-play-result: triggers when a user (must be member of the organization) completes a quiz in practice mode in the organization
      • journey-completed: triggers when a user (must be member of the organization) finishes an exam journey started by an exam of the organization, see GET /exam:journey
      • api: triggers when a manual API call is made (useful for testing and debugging), see POST /organization:webhook:trigger
  • [!] string[url] endpoint: URL to send webhook notifications to
  • string method: HTTP method to use for webhook notifications
    • possible values: POST / GET
    • default: POST
  • string authentication: type of authentication
    • possible values: none / key
      • none: no authentication
      • key: use a secret key (or password) for authentication
    • default: none
  • string authentication_send: how to send authentication data
    • possible values: header / bearer / data
      • header: as header field
      • bearer: as Bearer token in Authorization header
      • data: as data field (in body or query string)
    • default: data
  • string authentication_send_header: name of header field to send authentication data in (required if authentication is set to key and authentication_send is set to header)
  • string authentication_send_data: name of data field to send authentication data in (required if authentication is set to key and authentication_send is set to data)
  • string authentication_key: secret key (or password) to use for authentication (required if authentication is set to key)
  • string authentication_key_custom: custom field name to use as the authentication key
    • required if authentication is set to key
    • mutually exclusive with authentication_key
  • string[json] extra_data: additional data (as JSON encoded string) to send with the webhook notification
  • string retry: how to retry webhook notifications on failure
    • possible values: none / error
      • none: no retry
      • error: delayed retry on any error
    • default: error

[] Output:

  • string organization: organization identification string
  • string webhook: webhook identification string

PATCH /organization:webhook

Update organizational webhook.

[] Input:

  • [!] string organization: organization identification string
  • [!] string webhook: webhook identification string
  • boolean active: enable or disable webhook

DELETE /organization:webhook

Remove webhook from organization.

[] Input:

  • [!] string organization: organization identification string
  • [!] string webhook: webhook identification string

POST /organization:webhook:trigger

Trigger an organizational webhook call with optional custom payload. Only triggers webhooks with trigger_event set to api!

[] Input:

  • [!] string organization: organization identification string
  • [!] string webhook: webhook identification string
  • string[json] data: custom payload data to be sent with the webhook call