> ## Documentation Index
> Fetch the complete documentation index at: https://docs.series.hr/llms.txt
> Use this file to discover all available pages before exploring further.

# Promote User

> Promote a user to the next higher rank in the group

<Warning>
  **Requires Premium or Enterprise subscription**
</Warning>

## Overview

Promotes a user to the next higher rank in the linked Roblox group. 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
* Related ranking 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

<ParamField path="userId" type="string" required>
  The Roblox user ID to promote
</ParamField>

## Request Body

<ParamField body="comment" type="string">
  Optional reason/comment for the promotion. This will be logged in ranking history and disciplinary records.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="UserId" type="string">
      The Roblox user ID that was promoted
    </ResponseField>

    <ResponseField name="Action" type="string">
      The action performed (`promote`)
    </ResponseField>

    <ResponseField name="PreviousRank" type="number">
      The user's previous rank number
    </ResponseField>

    <ResponseField name="PreviousRole" type="string">
      The user's previous role name
    </ResponseField>

    <ResponseField name="NewRank" type="number">
      The user's new rank number
    </ResponseField>

    <ResponseField name="NewRole" type="string">
      The user's new role name
    </ResponseField>

    <ResponseField name="WorkspaceId" type="string">
      The workspace ID
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.series.hr/ranking/promote/714760171 \
    -H "apikey: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"comment": "Passed training evaluation"}'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('https://api.series.hr/ranking/promote/714760171', {
    method: 'POST',
    headers: {
      'apikey': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      comment: 'Passed training evaluation'
    })
  });

  const data = await response.json();
  ```

  ```lua Lua (Roblox) theme={null}
  local HttpService = game:GetService("HttpService")

  local response = HttpService:RequestAsync({
      Url = "https://api.series.hr/ranking/promote/714760171",
      Method = "POST",
      Headers = {
          ["apikey"] = "YOUR_API_KEY",
          ["Content-Type"] = "application/json"
      },
      Body = HttpService:JSONEncode({
          comment = "Passed training evaluation"
      })
  })

  local data = HttpService:JSONDecode(response.Body)
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.series.hr/ranking/promote/714760171',
      headers={
          'apikey': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={'comment': 'Passed training evaluation'}
  )

  data = response.json()
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "success": true,
  "data": {
    "UserId": "714760171",
    "Action": "promote",
    "PreviousRank": 5,
    "PreviousRole": "Trainee",
    "NewRank": 20,
    "NewRole": "Junior Staff",
    "WorkspaceId": "a7d5339a-5531-4336-99c6-6f3249c9ac20"
  }
}
```

## Error Responses

<AccordionGroup>
  <Accordion title="400 - Already at Highest Rank">
    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": 400,
        "message": "Validation error: User is already at the highest rank"
      }
    }
    ```
  </Accordion>

  <Accordion title="400 - Rank Limit Exceeded">
    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": 400,
        "message": "Cannot promote beyond rank 100 (Max. Promotion Rank limit)"
      }
    }
    ```
  </Accordion>

  <Accordion title="403 - Premium Required">
    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": 403,
        "message": "Ranking management requires a Premium or Enterprise subscription"
      }
    }
    ```
  </Accordion>

  <Accordion title="404 - User Not in Group">
    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": 404,
        "message": "User is not a member of the group"
      }
    }
    ```
  </Accordion>

  <Accordion title="429 - Rate Limit">
    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": 429,
        "message": "Rate limit exceeded for ranking endpoints: 50 requests per second."
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Side Effects

When a user is promoted, the following actions occur automatically:

**For all users (workspace members and group-only members):**

1. **Roblox Group Update** - User's rank in the Roblox group is updated
2. **Ranking History** - Entry logged with timestamp, author, and comment
3. **Audit Log** - Action logged with workspace member or group-only indicator

**Additionally for workspace members only:**
4\. **Workspace Data Update** - User's `CurrentRank` and `CurrentRole` are updated
5\. **Disciplinary Log** - Record added to user's disciplinary file
6\. **Suggestions Cleared** - Pending promotion suggestions for the user are removed

## Rate Limit

**50 requests per second** per API key


## OpenAPI

````yaml POST /ranking/promote/{userId}
openapi: 3.0.0
info:
  title: Series API
  version: 1.0.0
  description: >-
    Series API — a free REST API by Sailboat Games, LLC that lets Roblox
    communities programmatically manage workspaces, staff, sessions, time-off
    and activity data.
  contact:
    name: Sailboat Games, LLC.
    email: admin@sailboatgames.com
servers:
  - url: https://api.series.hr
    description: Production API
security:
  - ApiKeyAuth: []
paths:
  /ranking/promote/{userId}:
    post:
      tags:
        - Ranking
      summary: Promote User
      description: >-
        Promote a user to the next higher rank. Requires Premium or Enterprise
        subscription.
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: The Roblox user ID to promote
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                comment:
                  type: string
                  description: Optional reason/comment for the promotion
      responses:
        '200':
          description: User promoted
        '400':
          description: Already at highest rank
        '403':
          description: Premium/Enterprise subscription required
        '404':
          description: User not found
        '429':
          description: Rate limit exceeded
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: apikey
      description: >-
        Pass your API key in the `apikey` header. Alternatively, the `x-api-key`
        header is also accepted.

````