This article was created from a community discussion.
Ranks are a great way to recognize members, encourage participation, and add a little extra personality to your community experience. Most of the time, ranks are earned automatically based on criteria like points, posts, time as a member, role, or permissions.
But sometimes, you may want to assign a special rank manually.
For example, maybe you want to recognize a subject matter expert, highlight a customer champion, identify a staff member, or award a special status based on activity happening outside the community. In those cases, you can update a user’s rank directly through the Vanilla API.
A Quick Note About How Ranks Work Today
In the current rank system, a user can only have one rank at a time.
Vanilla will always assign the user the highest-level rank they qualify for. That means if you manually assign a rank, but the user later qualifies for a higher-level rank through points, time, role, permission, or another criterion, they may move out of the manually assigned rank and into the higher-level one.
Because of that, if you’re creating a special manually applied rank, you’ll usually want to give it a higher level than your standard automatic ranks.
For example, a manually applied “Super Star” rank might have:
- Name: Super Special Manually Applied Rank
- Label: Super Star
- Level: 900
- Criteria: Applied Manually
That high level helps make sure the special rank is not accidentally overridden by your normal points-based or activity-based ranks.
Updating a User’s Rank with the API
To assign the rank, you can update the user’s rankID using the PATCH /api/v2/users/{id} endpoint.
Example:
curl --request PATCH \
--url https://yourcommunity.example.com/api/v2/users/159 \
--header "Authorization: Bearer $VANILLA_AUTH_TOKEN" \
--header "X-Requested-With: vanilla" \
--header "Content-Type: application/json" \
--data '{
"rankID": "119"
}'
In this example:
159 is the user ID119 is the rank ID you want to assign
A successful response will return the updated user object. You can confirm the update by checking for the new rankID and rank label in the response:
{
"label": "Super Star",
"labelHtml": "Super Star",
"rankID": 119
}
Once updated, the user will display with the new rank label in the community.
Things to Keep in Mind
A few important notes:
- The rank should be configured as manually applied.
- 🚨 Users can only have one rank at a time in the current rank system.
- 🚨 Vanilla will assign the highest-level rank the user qualifies for.
- 🚨 If the user qualifies for a higher-level automatic rank later, they may move out of the manually applied rank.
- To avoid that, manually applied special ranks are usually set at a higher level than standard automatic ranks.
- Ranks are different from roles. Roles control permissions and access, while ranks are used for recognition, progression, and rank-based abilities.
Looking Ahead to Rank Journeys
This level-management consideration applies to the current rank system.
With our upcoming Rank Journeys feature, you won’t need to worry about levels in the same way. Rank Journeys will provide a more flexible way to manage progression paths and member recognition.
That said, like all of our features, Rank Journeys is being built API-first. This API-based method of updating a user’s rank will still be supported, so you’ll continue to have options for automation, integrations, and custom workflows.
How Are You Using Ranks?
Ranks can be a powerful part of your gamification strategy, whether you’re recognizing experts, encouraging participation, rewarding helpfulness, or creating special community moments.
How are you using ranks to drive gamification in your community? Are you using them for member milestones, staff identification, expert programs, advocacy, or something totally unique?
We’d love to hear what you’re building. ✨