Grant a custom badge through the API

Custom badges that you have created on your forum can be granted through the API. This is a great way to award badges without having to use custom badge SQL.

To grant a badge through the API, you need to know the username of the user that you wish to grant the badge to, and the ID of the badge you wish to grant. You also need to make sure you have generated an All Users API Key from your site’s Admin/API section.

Finding your API Key

This screenshot is from my local development site. Generally, you need to be very careful about sharing your API keys:

Finding the Badge ID

You can get the Badge ID from the badge’s URL. Go to your Admin/Badges section and then click on the badge that you wish to grant. The URL will look something like this: The last number in the URL is the badge ID.

Making the API call

To test an API call, you can try granting a badge using curl or Postman. Here is how I grant a badge from my computer’s terminal with curl.

First, to make things easier, set an api_key variable:


Then to grant a badge with the ID of 102 to the user bobby:

curl -X POST "" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: $api_key" \
-H "Api-Username: system" \
-F "username=bobby" \
-F "badge_id=102" \
-F "reason="

The reason parameter is optional. If you supply it, it must be set to the URL of a topic or a post on your site.

You should get a JSON response with details about the badge and when it was granted.


Has anybody added a badge (or flair) via Zapier to Discourse API like outlined here?

Also, seems like a great candidate for an action via the official integration, @HAWK.


See also How to create a custom badge with an image through the API, which shows how to upload, and also has another example of granting the badge (in python).

1 Like

What is the reason this method is not described in the API Docs at

I couldn’t find this there.

Because it doesn’t seem to be anyone’s job to keep those docs complete or up to date and some kind soul posted these instructions here. Generally, the documentation for the API is Reverse engineer the Discourse API and looking at the source.