Skip to main content
POST
/
ranking
/
set-rank
/
{userId}
/
{rankNumber}
Set Rank
curl --request POST \
  --url https://api.series.hr/ranking/set-rank/{userId}/{rankNumber} \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '
{
  "comment": "<string>"
}
'
Requires Premium or Enterprise subscription

​
Overview

Sets a user’s rank to a specific rank number in the linked Roblox group. This allows jumping multiple ranks at once, unlike promote/demote which move one rank at a time. The user does not need to be a workspace member - they only need to be a member of the Roblox group. For workspace members:
  • Action is logged to ranking history, audit log, and disciplinary records
  • Workspace member data is updated
  • Both promotion and demotion suggestions are cleared
For non-workspace members (group members only):
  • Action is logged to ranking history and audit log only
  • No disciplinary record is created
  • All logs indicate the action was performed via API

​
Path Parameters

​
userId
string
required
The Roblox user ID to set rank for
​
rankNumber
integer
required
Target rank number (0-255). Must correspond to an existing role in the workspace.

​
Request Body

​
comment
string
Optional reason/comment for the rank change. This will be logged in ranking history and disciplinary records.

​
Response

​
success
boolean
Whether the request was successful
​
data
object

​
Example

curl -X POST https://api.series.hr/ranking/set-rank/714760171/50 \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"comment": "Reinstated to previous rank"}'

​
Response Example

{
  "success": true,
  "data": {
    "UserId": "714760171",
    "Action": "set-rank",
    "PreviousRank": 5,
    "PreviousRole": "Trainee",
    "NewRank": 50,
    "NewRole": "Senior Staff",
    "WorkspaceId": "a7d5339a-5531-4336-99c6-6f3249c9ac20"
  }
}

​
Error Responses

{
  "success": false,
  "error": {
    "code": 400,
    "message": "Validation error: RankNumber must be a valid integer between 0 and 255"
  }
}

{
  "success": false,
  "error": {
    "code": 400,
    "message": "Validation error: User is already at the specified rank"
  }
}

{
  "success": false,
  "error": {
    "code": 400,
    "message": "Cannot set rank beyond 100 (Max. Promotion Rank limit)"
  }
}

{
  "success": false,
  "error": {
    "code": 403,
    "message": "Ranking management requires a Premium or Enterprise subscription"
  }
}

{
  "success": false,
  "error": {
    "code": 404,
    "message": "User is not a member of this workspace"
  }
}

{
  "success": false,
  "error": {
    "code": 404,
    "message": "Role with rank 50 not found in workspace"
  }
}

{
  "success": false,
  "error": {
    "code": 429,
    "message": "Rate limit exceeded for ranking endpoints: 50 requests per second."
  }
}

​
Side Effects

When a user’s rank is set, the following actions occur automatically:
  1. Roblox Group Update - User’s rank in the Roblox group is updated
  2. Workspace Data Update - User’s CurrentRank and CurrentRole are updated
  3. Ranking History - Entry logged with timestamp, author, and comment
  4. Disciplinary Log - Record added to user’s disciplinary file
  5. Suggestions Cleared - All pending ranking suggestions (both promotion and demotion) for the user are removed

​
Rank Limits

When setting a rank higher than the user’s current rank, the following limits apply:
  • Max Promotion Rank - Cannot set rank higher than this value
  • Max Auto-Ranking Rank - Cannot set rank higher than this value
These limits are configured in the workspace settings.

​
Use Cases

  • Reinstatement - Restore a user to their previous rank after a temporary demotion
  • Bulk Adjustments - Quickly adjust ranks during restructuring
  • Administrative Actions - Set exact ranks for special circumstances
  • Onboarding - Set new members to a specific starting rank

​
Rate Limit

50 requests per second per API key

Authorizations

​
apikey
string
header
required

Pass your API key in the apikey header. Alternatively, the x-api-key header is also accepted.

Path Parameters

​
userId
string
required

The Roblox user ID

​
rankNumber
integer
required

Target rank number (0-255)

Required range: 0 <= x <= 255

Body

application/json
​
comment
string

Optional reason/comment for the rank change

Response

Rank set