Skip to main content

Award points via the Web Services API

This features requires Level Up XP+

The Web Services API of Moodle can be used to award points to students. This can be useful to automate the attribution of points for actions taken in another system.

Pre-requisites​

  • An XP+ plan including API support
  • Moodle Web Services configured and enabled for the function local_xp_award_points
  • A Web Service token to authenticate with the API

Constructing the request​

info

This guide assumes that the default rest Web Service plugin is used. If you are using another Web Service plugin than the standard one, please refer to their documentation.

The Web Service function to award points is local_xp_award_points, and it requires the following arguments:

  • userid (int): The user ID of the Moodle user to whom points should be given
  • points (int): The number of points to give to the user
  • courseid (int): The ID of the course in which the points are given, when XP is used sitewide, use 1.

The default rest Web Service plugin requires:

  • All requests to be POST.
  • All requests to be sent to https://moodle.example.com/webservice/rest/server.php.
  • All requests to be form encoded, not the typical JSON.
  • A body (or query) parameter wstoken to declare the contain the authentication token.
  • A body (or query) parameter wsfunction to reference the Web Service function to call.
  • A body (or query) parameter moodlewsrestformat with value json to get a JSON response.

Sample query​

Here is a sample query awarding 10 points to the user with ID 20, in the course 30. Replace WSTOKEN with your Webservice Token`.

http -f POST https://moodle.example.com/webservice/rest/server.php wstoken=WSTOKEN wsfunction=local_xp_award_points moodlewsrestformat=json userid=10 points=20 courseid=30

Get HTTPie CLI

Response​

After a successful request, the response will include an object with the updated total number of points of the user, for instance 1200 below:

{"xp": 1200}

Notes​

  • The permissions are checked in the system context when used sitewide, else in the course context.
  • The user calling the API must have the permissions block/xp:manage.
  • The user to receive points must have the permission block/xp:earnxp.