Award points with the Moodle web services API

This feature requires Level Up XP+ Premium.

You can use local_xp_award_points in the Moodle web services API to award points from an external system.

Your XP+ plan must include API support. You also need a Moodle web service and a token. To create a service, create a web service.

Award points

The local_xp_award_points function requires these arguments:

Argument	Type	Description
`userid`	Integer	The ID of the Moodle user who receives the points.
`points`	Integer	The number of points to award. The value must be greater than `0`.
`courseid`	Integer	The course ID. If you use XP sitewide, use `1`.

If you do not know the userid, find the user ID before you award the points.

info

This page uses Moodle's standard REST protocol. If you use a different web service protocol, see its documentation.

Send a POST request to this URL:

https://moodle.example.com/webservice/rest/server.php

Replace https://moodle.example.com with the address of your Moodle site. Encode the request data as application/x-www-form-urlencoded. Do not encode the request data as JSON.

Include these form fields:

Set wstoken to your web service token.
Set wsfunction to local_xp_award_points.
Set moodlewsrestformat to json.
Set userid, points, and courseid to the required values.

Example request

This example awards 10 points to user 20 in course 30. Replace YOUR_TOKEN with your web service token.

HTTPie
curl
Plain text

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

Get HTTPie CLI.

curl --request POST https://moodle.example.com/webservice/rest/server.php \
  --data "wstoken=YOUR_TOKEN" \
  --data "wsfunction=local_xp_award_points" \
  --data "moodlewsrestformat=json" \
  --data "points=10" \
  --data "userid=20" \
  --data "courseid=30"

POST /webservice/rest/server.php HTTP/1.1
...
Content-Type: application/x-www-form-urlencoded; charset=utf-8

wstoken=YOUR_TOKEN&wsfunction=local_xp_award_points&moodlewsrestformat=json&courseid=30&userid=20&points=10

Response

Moodle returns the user's new points total in xp. In this example, the new total is 1200:

{
  "xp": 1200
}

Find a user ID

The award function requires the numeric Moodle user ID. If you know another identifier, use core_user_get_users_by_field to find the ID.

Set field to id, username, idnumber, or email. The values argument must always be an array. For one value, send one array item.

This example finds the user with the username admin:

HTTPie
curl
Plain text

http -f POST https://moodle.example.com/webservice/rest/server.php \
  wstoken=YOUR_TOKEN \
  wsfunction=core_user_get_users_by_field \
  moodlewsrestformat=json \
  field=username \
  values[]=admin

curl --request POST https://moodle.example.com/webservice/rest/server.php \
  --data "wstoken=YOUR_TOKEN" \
  --data "wsfunction=core_user_get_users_by_field" \
  --data "moodlewsrestformat=json" \
  --data "field=username" \
  --data "values[]=admin"

POST /webservice/rest/server.php HTTP/1.1
...
Content-Type: application/x-www-form-urlencoded; charset=utf-8

wstoken=YOUR_TOKEN&wsfunction=core_user_get_users_by_field&moodlewsrestformat=json&field=username&values[]=admin

Moodle returns only the users and fields that the user calling the web service can view. Moodle can return an empty array if the specified value does not match a user or if that user cannot view the selected field. This shortened response shows the values that you need:

[
  {
    "id": 2,
    "username": "admin"
  }
]

Use the id value from the matching object as userid. In this example, the userid is 2.

Create a web service

These steps create a new service that can award points:

Enable Moodle web services and the web service protocol that you want to use, see the Moodle documentation.
Go to Site administration > Server > Web services > External services, and then select Add.
Enter a name, select Enabled and Authorised users only, and then select Add service.
Select Add functions, and add local_xp_award_points.
Add core_user_get_users_by_field if you want to find user IDs with the API.
Return to External services, select Authorised users for the new service, and add the user who will call the web service.
Get a web service token for the user who will call the web service.

For complete setup instructions, see Using web services in the Moodle documentation.

Required capabilities

Capability	Required for	Scope or details
`block/xp:earnxp`	Points recipient	In the course context, or the system context when XP is used sitewide.
`block/xp:manage`	User calling the web service	In the course context, or the system context when XP is used sitewide.
Web service protocol capability	User calling the web service	For REST, use `webservice/rest:use`. Check the documentation for other protocols.
Capabilities for `core_user_get_users_by_field`	User calling the web service	Moodle lists the required capabilities on the service's Functions page.

Award points​

Example request​

Response​

Find a user ID​

Create a web service​

Required capabilities​