> ## Client identification
>
> Requests to this API should include a `Client-Platform` header alongside
> `Authorization`, identifying the application, tool, or model making the
> request. This is used for integration support and analytics.
>
> Use your model or tool name, for example `claude-code` or `chatgpt`.
>
> Example:
>
> ```bash
> curl https://api.salaryboxapp.com/... \
>   -H "Authorization: Api-Key <api-key>" \
>   -H "Client-Platform: claude-code"
> ```

# Set Staff Role

PUT https://api.salaryboxapp.com/v2/customer/v1/staff/{salarybox_id}/role
Content-Type: application/json

Changes the role of a staff member. Shared rules: see [Writing Data](/writing-data).

- Only an Admin key can call this endpoint.
- `role` must be one of `Employee`, `Branch Admin`, `Attendance Manager`, `Advanced Attendance Manager` or `Custom`. `Admin` is not accepted, and an Admin's role cannot be changed.
- `Custom` needs Custom Permissions turned on in the SalaryBox app's settings. After setting it, use Set Staff Permissions.
- Permissions saved for the Custom role are kept when the role changes, and apply again if the role is set back to Custom.


Reference: https://docs.salarybox.in/api-reference/staff/role-set

## Authentication

- `Authorization` header (required) (prefixed with ` Api-Key   `) — Format: "Api-Key \{api-key}"

## Request

### Path parameters

- `salarybox_id` (string, required) — SalaryBox ID of the staff member.

### Body (application/json)

This endpoint expects a StaffRoleSetRequest.

- `role` (enum, required) — The new role (case-sensitive). - `Employee`: can mark their own attendance. - `Branch Admin`: can mark attendance and process salary of staff in their branch. - `Attendance Manager`: can mark today's attendance of all staff. - `Advanced Attendance Manager`: can mark all days' attendance of all staff. - `Custom`: has the permissions an admin chooses (see Set Staff Permissions).
  - Allowed values: `Employee`, `Branch Admin`, `Attendance Manager`, `Advanced Attendance Manager`, `Custom`

## Response

### 200

The role was set. Sending the role the staff member already has changes nothing and also returns `200`.

- `message` (string, required)
- `status` (boolean, required)
- `data` (StaffRoleSetResponseData, required)

## Errors

### 400 Bad Request Error

Validation failed, or the staff member is inactive.

- `message` (string, required)
- `status` (boolean, required)
- `errors` (map from string to any, optional, nullable)

### 403 Forbidden Error

The key owner may not make this change. Either the user who created the API key is no longer active, has been deleted, is no longer in the company, or no longer has the Admin or Custom role; the key owner is not an Admin; or the role is `Custom` and Custom Permissions is turned off for the company.

- `message` (string, required)
- `status` (boolean, required)
- `errors` (map from string to any, optional, nullable)

### 404 Not Found Error

No eligible active staff member with this `salarybox_id` exists in your company.

- `message` (string, required)
- `status` (boolean, required)
- `errors` (map from string to any, optional, nullable)

## Types

### StaffRoleSetResponseData

- `salarybox_id` (string, required)
- `role` (string, required)

## Examples

**Request**

```json
{
  "role": "Custom"
}
```

**Response**

```json
{
  "message": "Staff role updated successfully",
  "status": true,
  "data": {
    "salarybox_id": "ABCDEFGHIJ",
    "role": "Custom"
  }
}
```

**SDK Code**

```python Example
import requests

url = "https://api.salaryboxapp.com/v2/customer/v1/staff/ABCDEFGHIJ/role"

payload = { "role": "Custom" }
headers = {
    "Authorization": "Api-Key  <apiKey>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript Example
const url = 'https://api.salaryboxapp.com/v2/customer/v1/staff/ABCDEFGHIJ/role';
const options = {
  method: 'PUT',
  headers: {Authorization: 'Api-Key  <apiKey>', 'Content-Type': 'application/json'},
  body: '{"role":"Custom"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Example
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.salaryboxapp.com/v2/customer/v1/staff/ABCDEFGHIJ/role"

	payload := strings.NewReader("{\n  \"role\": \"Custom\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Api-Key  <apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Example
require 'uri'
require 'net/http'

url = URI("https://api.salaryboxapp.com/v2/customer/v1/staff/ABCDEFGHIJ/role")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Api-Key  <apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"role\": \"Custom\"\n}"

response = http.request(request)
puts response.read_body
```

```java Example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.put("https://api.salaryboxapp.com/v2/customer/v1/staff/ABCDEFGHIJ/role")
  .header("Authorization", "Api-Key  <apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"role\": \"Custom\"\n}")
  .asString();
```

```php Example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.salaryboxapp.com/v2/customer/v1/staff/ABCDEFGHIJ/role', [
  'body' => '{
  "role": "Custom"
}',
  'headers' => [
    'Authorization' => 'Api-Key  <apiKey>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Example
using RestSharp;

var client = new RestClient("https://api.salaryboxapp.com/v2/customer/v1/staff/ABCDEFGHIJ/role");
var request = new RestRequest(Method.PUT);
request.AddHeader("Authorization", "Api-Key  <apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"role\": \"Custom\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Example
import Foundation

let headers = [
  "Authorization": "Api-Key  <apiKey>",
  "Content-Type": "application/json"
]
let parameters = ["role": "Custom"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.salaryboxapp.com/v2/customer/v1/staff/ABCDEFGHIJ/role")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```