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
    • string organization: organization identification string
    • string/null id: external unique organization identifier (if set for the organization)
    • string name: 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 name: title of the organization

POST /organization

Create an organization.

[] Input:

  • [!] string name: 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 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
    • string user: user identification string
    • string name: name of the member
    • string/null department: name of the department (if member)
    • list permission
      • list organization: permission level to organization
      • list content: permission level to contents 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
  • 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
  • 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
  • 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
  • boolean notify: notify users
    • default: false

/user:organizations

GET /user:organizations

List all organizations a user is member of.

[] Input:

  • [!] string user: user identification string

[] Output:

  • list
    • string organization: organization identification string
    • string/null id: external unique organization identifier (if set for the organization)
    • string name: title of the organization
    • string link: link to the organization manager page
    • string/null department: name of the department (if member)
    • list permission
      • list organization: permission level to organization
      • list content: permission level to contents 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
  • 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
  • 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 name: 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 name: title of the webhook
  • [!] string trigger_event: type of event to trigger webhook
    • possible values: exam-play-result / quiz-play-result / 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
      • 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