How to integrate Discourse Gamification with an external system (redeem and award points)

[Discourse]

Since we launched Discourse Gamification a year ago, one of the most requested features from our roadmap has been the ability to make it possible to integrate Discourse Gamification with external gamification system . Examples are plenty:

• Integrate with existing gamification programs in companies

• ability to award points for events that happen outside of Discourse, like IRL events, or elsewhere online, like being a customer in a community, or buying a product.

• the ability to allow users to redeem their points for swag, products or benefits

Today, just in time for the plugin’s first anniversary, we made all of the above possible with a full API to handle custom scoring events .

This new system allows admins to:

• Award users a custom score event

• Award users with negative score events, to accommodate redeem or penalties events

• Update and list custom events previously created

API

Points awarded via API will take up to 1 hour to reflect on a user’s overall score for events created with the current date, and up to 24 hours for events created in the last 10 days. For events created with a date older than 10 days, you can use the Recalculate Scores button in the admin gamification UI, or run the backfill rake task: rake gamification_scores:backfill_scores_from[YYYY-MM-DD].

There are 3 different API endpoints currently.

List Events

Returns up to 100 events. You can filter by id, user_id, and/or date.

curl https://<example_url>/admin/plugins/gamification/score_events.json \
-H 'API-Key: <api_key_here>' \
-H 'API-Username: <api_username_here>'

You can also list specific user or date events:

curl https://<example_url>/admin/plugins/gamification/score_events.json?user_id=1&date=2023-05-01 \
-H 'API-Key: <api_key_here>' \
-H 'API-Username: <api_username_here>'

Create Event

curl -X POST https://<example_url>/admin/plugins/gamification/score_events.json \
-H 'API-Key: <api_key_here>' \
-H 'API-Username: <api_username_here>' \
-H "Content-Type: application/json" \
-d '{
  "user_id": 13,
  "date": "2023-04-14",
  "points": 15,
  "description": "May 2023 Karaoke attendee"
}'

Alternate syntax using jo:

jo -p user_id="13" date="2023-04-14" points="15" description="May 2023 Karaoke atendee" | curl --json @- -XPOST http://example/admin/plugins/gamification/score_events -H "Api-Key: apikeyhere" -H "Api-Username: system"

Update Event

The update endpoint requires id and points. You can optionally update description. Note that user_id and date cannot be changed after creation.

curl -L -X PUT https://<example_url>/admin/plugins/gamification/score_events.json \
-H 'API-Key: <api_key_here>' \
-H 'API-Username: <api_username_here>' \
-H "Content-Type: application/json" \
-d '{
  "id": 6,
  "points": 25,
  "description": "May 2023 keynote attendee"
}'

Alternate syntax using jo:

jo -p id="11" points="25" description="May 2023 Karaoke attendee" | curl --json @- -XPUT http://example/admin/plugins/gamification/score_events -H "Api-Key: apikeyhere" -H "Api-Username: system"

Last edited by @MarkDoerr 2025-12-03T01:34:43Z

Last checked by @MarkDoerr 2025-12-19T22:30:29Z

Check document

Perform check on document:

[not-ethan (Ethan)]

Is/will there be a way to do this through the UI?

[Falco]

That’s something I would consider if an Enterprise customer wants to sponsor it.

[jordan-violet]

This is incredible. We’re just in the middle of starting and piloting an ambassador/champions program, and we’ve been using Airtable to monitor webhooks from our different sources (Discourse, GitHub, Ghost) and aggregate our champions program there. I’m excited to check this out and see if it could be used for us to manage/monitor our program and contributions.

It would be great if you could award points to a user group instead of a user. The use case for us as an enterprise customer would be that we essentially want to award points to the company the users work for and aggregate their points for each company. What is the feasibility of something like this?

[Shawnpinto (Shawn)]

Ahh I don’t know how to use this
We’re using a business plan.

I wish we could operate this via the UI.

But still, thanks for building this team! Keep up the good work.

[satonotdead]

That could help to give one-time points within Discourse with Automation plugin?

[colin.mckibben]

How does redeeming points work? I see there is an update event that could be used to subtract points from individual events, but that seems like an inefficient way to redeem points.

[colin.mckibben]

Also, when attempting to list events in my discourse instance, I get a 404.

GET https://developer.sailpoint.com/discuss/admin/plugins/gamification/score_events.json

404 Not Found
“The requested URL or resource could not be found.”

I have enabled the plugin and can configure it through the UI. Am I missing something to enable the external system API?

[Falco]

@colin.mckibben

How does redeeming points work? I see there is an update event that could be used to subtract points from individual events, but that seems like an inefficient way to redeem points.

It may be my decade of experience working at banks, but the way I envision redeeming points is issuing negative value custom events.

For example, let’s say you have a user who wants to redeem points for a T-Shirt, and that T-Shirt costs 10k points. The flow on your redeeming system would be:

1. Check if the user has enough points:

   curl https://meta.discourse.org/u/falco.json -s | jq . | grep score
       "gamification_score": 89386,
   

2. Issue a “point withdraw” event

   jo -p user_id="13" date="2023-04-14" points="-10000" description="T-Shirt Redeem - order #123" | curl --json @- -XPOST http://example/admin/plugins/gamification/score_events -H "Api-Key: apikeyhere" -H "Api-Username: system"
   

You will want to wrap this in a semaphore of some sorts, as this is the text book example of using those, but that is the gist of the proposed workflow.

This is a very recent feature, so let me know if the proposed workflow doesn’t work correctly.

@colin.mckibben

Also, when attempting to list events in my discourse instance, I get a 404.

GET https://developer.sailpoint.com/discuss/admin/plugins/gamification/score_events.json

It’s working fine for me, both in the browser and via API. It’s an admin endpoint, so you need to be a logged in admin via browser, or pass API keys like explained in the OP.

[colin.mckibben]

@Falco

It may be my decade of experience working at banks, but the way I envision redeeming points is issuing negative value custom events.

Ok, that’s what I was missing. I didn’t realize you could issue negative points. That should work perfectly then.

@Falco

It’s working fine for me, both in the browser and via API. It’s an admin endpoint, so you need to be a logged in admin via browser, or pass API keys like explained in the OP.

I was using expired credentials. Thanks for confirming anyway.

[colin.mckibben]

@Falco

Are there any plans to add scopes to this API? It appears that the only way I can create or update scores is by having an admin API key that has global access. I would love to have a scope that restricts a key to just being able to update scores. This would give me more confidence using this API in automation tools as I wouldn’t have an admin key that can do much more than just update scores.

[Falco]

@colin.mckibben

Are there any plans to add scopes to this API?

That’s a good idea, but I personally don’t have the bandwidth to work on this in the near future.

If you are keen on sponsoring this feature, please contact our support channel so we can get you a quote.

[ok_dashcam (orlie)]

Facing the same issue here:

{"errors":["The requested URL or resource could not be found."],"error_type":"not_found"}

[Falco]

@ok_dashcam

Facing the same issue here:

{"errors":["The requested URL or resource could not be found."],"error_type":"not_found"}

That error was caused by

@colin.mckibben

I was using expired credentials. Thanks for confirming anyway.

So you want to check yours

[ok_dashcam (orlie)]

Thanks, I’m also gonna update to latest just in case

[ok_dashcam (orlie)]

Updating to latest worked! ty

[EaZee (Chris Bunge)]

I’ve been testing this a bit today. I see the events I can track, though unsure if there is a direct query to view only events by userid. Looking for a way to maybe have an audit log or present to users how they have gained/lost points.

[satonotdead]

There is something logged in UI when API call get sucess adding points?

[Alex_王]

Awesome! And I have another suggestion, is it possible to add a feature that enable users to redeem points for subscriptions in the ui interface? And the ability to add a limit to the number of points a user can earn per day on an event ( like create topics).

Thanks!

[Falco]

@satonotdead

There is something logged in UI when API call get sucess adding points?

No, the feature is 100% API based. You can call the “List Events” endpoint to check for events as described in the OP.