Update member role

Endpoint

PUT /organizations/{org_id}/users/{user_id}/role

This endpoint updates the role of a specific member within the organization.

Request

Replace {org_id} with your Organization ID and {user_id} with the numeric ID of the member whose role you want to change.

Headers

• Authorization: Bearer {your_access_token}
• Accept: application/json
• X-Tallyfy-Client: APIClient
• Content-Type: application/json

Body (JSON)

The request body requires a JSON object specifying the new role.

• role (string, required): The new role name (e.g., admin, standard, light). Check organization settings or documentation for exact available role names.

Example Body:

{
  "role": "light"
}

Code samples

Javascript

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';
const userId = 12345; // ID of the member whose role to update
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/users/${userId}/role`;

const roleData = {
  role: "admin" // Promote to Admin (ensure role name is valid: "admin", "standard", "light")
};

const headers = new Headers();
headers.append('Authorization', `Bearer ${accessToken}`);
headers.append('Accept', 'application/json');
headers.append('X-Tallyfy-Client', 'APIClient');
headers.append('Content-Type', 'application/json');

fetch(apiUrl, {
    method: 'PUT',
    headers: headers,
    body: JSON.stringify(roleData)
})
.then(response => {
    return response.json().then(data => { // Attempt to parse JSON regardless of status
        if (!response.ok) {
            console.error(`Failed to update role for member ${userId}:`, data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return data; // Pass successful data along
    });
})
.then(data => {
    console.log(`Successfully updated role for member ${userId}:`);
    console.log(JSON.stringify(data, null, 2)); // Response likely shows the updated user profile
})
.catch(error => {
    console.error(`Error updating role for member ${userId}:`, error.message);
});

Python

import requests
import json
import os

access_token = os.environ.get('TALLYFY_ACCESS_TOKEN', 'YOUR_PERSONAL_ACCESS_TOKEN')
org_id = os.environ.get('TALLYFY_ORG_ID', 'YOUR_ORGANIZATION_ID')
user_id = 12345 # ID of the member
api_url = f'https://go.tallyfy.com/api/organizations/{org_id}/users/{user_id}/role'

headers = {
    'Authorization': f'Bearer {access_token}',
    'Accept': 'application/json',
    'X-Tallyfy-Client': 'APIClient',
    'Content-Type': 'application/json'
}

role_payload = {
    'role': 'light' # Example: Demote to Light user (valid roles: "admin", "standard", "light")
}

response = None
try:
    response = requests.put(api_url, headers=headers, json=role_payload)
    response.raise_for_status() # Raises HTTPError for bad responses (4xx or 5xx)

    updated_member = response.json()
    print(f'Successfully updated role for member {user_id}:')
    print(json.dumps(updated_member, indent=4))

except requests.exceptions.HTTPError as http_err:
    error_details = ""
    try:
        if response is not None:
             error_details = response.json()
    except json.JSONDecodeError:
        if response is not None:
             error_details = response.text

    print(f"HTTP error occurred updating role for member {user_id}: {http_err}")
    print(f"Response Body: {error_details}")

except requests.exceptions.RequestException as req_err:
    print(f"Request failed updating role for member {user_id}: {req_err}")
except json.JSONDecodeError:
    print(f"Failed to decode successful JSON response for member {user_id} role update")
    if response is not None:
        print(f"Response Text: {response.text}")
except Exception as err:
     print(f"An unexpected error occurred: {err}")

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.IOException;
// Requires a JSON library like Jackson or Gson
// import com.fasterxml.jackson.databind.ObjectMapper;
// import java.util.Map;

public class UpdateMemberRole {
    public static void main(String[] args) {
        String accessToken = System.getenv().getOrDefault("TALLYFY_ACCESS_TOKEN", "YOUR_PERSONAL_ACCESS_TOKEN");
        String orgId = System.getenv().getOrDefault("TALLYFY_ORG_ID", "YOUR_ORGANIZATION_ID");
        int userId = 12345;
        String newRole = "standard"; // Must be "admin", "standard", or "light"
        String apiUrl = String.format("https://go.tallyfy.com/api/organizations/%s/users/%d/role", orgId, userId);

        // --- Payload Construction ---
        // Using Jackson/Gson recommended:
        /*
        ObjectMapper mapper = new ObjectMapper();
        Map<String, String> roleData = Map.of("role", newRole);
        String jsonPayload;
        try {
            jsonPayload = mapper.writeValueAsString(roleData);
        } catch (Exception e) {
            System.err.println("Failed to serialize JSON: " + e.getMessage());
            return;
        }
        */
        // Simple manual JSON string:
        String jsonPayload = String.format("{\"role\": \"%s\"}", newRole);
        // --- End Payload ---

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(apiUrl))
                .header("Authorization", "Bearer " + accessToken)
                .header("Accept", "application/json")
                .header("X-Tallyfy-Client", "APIClient")
                .header("Content-Type", "application/json")
                .PUT(HttpRequest.BodyPublishers.ofString(jsonPayload))
                .build();

        try {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() == 200) {
                System.out.println("Successfully updated role for member " + userId + " to " + newRole + ":");
                System.out.println(response.body());
                // TODO: Consider parsing JSON response
            } else {
                System.err.println("Failed to update role for member " + userId + ". Status: " + response.statusCode());
                System.err.println("Response Body: " + response.body());
            }
        } catch (IOException | InterruptedException e) {
            System.err.println("Request failed: " + e.getMessage());
            Thread.currentThread().interrupt();
        } catch (Exception e) {
             System.err.println("An unexpected error occurred: " + e.getMessage());
             e.printStackTrace();
        }
    }
}

Go

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io/ioutil"
  "net/http"
  "os"
  "strconv"
    "time"
)

func main() {
  accessToken := os.Getenv("TALLYFY_ACCESS_TOKEN")
    if accessToken == "" { accessToken = "YOUR_PERSONAL_ACCESS_TOKEN" }
  orgId := os.Getenv("TALLYFY_ORG_ID")
    if orgId == "" { orgId = "YOUR_ORGANIZATION_ID" }
    userId := 12345
    newRole := "admin" // Must be "admin", "standard", or "light"
    apiUrl := fmt.Sprintf("https://go.tallyfy.com/api/organizations/%s/users/%s/role", orgId, strconv.Itoa(userId))

  roleData := map[string]interface{}{
    "role": newRole,
  }

  jsonData, err := json.Marshal(roleData)
  if err != nil {
        fmt.Printf("Error marshalling JSON: %v\n", err)
        return
    }

  client := &http.Client{Timeout: 15 * time.Second}
  req, err := http.NewRequest(http.MethodPut, apiUrl, bytes.NewBuffer(jsonData))
    if err != nil {
        fmt.Printf("Error creating update role request for user %d: %v\n", userId, err)
        return
    }

  req.Header.Set("Authorization", "Bearer "+accessToken)
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-Tallyfy-Client", "APIClient")
  req.Header.Set("Content-Type", "application/json")

  resp, err := client.Do(req)
    if err != nil {
        fmt.Printf("Error executing update role request for user %d: %v\n", userId, err)
        return
    }
  defer resp.Body.Close()

  body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Printf("Error reading update role response body for user %d: %v\n", userId, err)
        return
    }

  if resp.StatusCode != http.StatusOK {
    fmt.Printf("Failed to update role for user %d. Status: %d\nBody: %s\n", userId, resp.StatusCode, string(body))
    return
  }

  fmt.Printf("Successfully updated role for member %d to %s:\n", userId, newRole)
    // Pretty print JSON response
    var prettyJSON bytes.Buffer
    if err := json.Indent(&prettyJSON, body, "", "  "); err == nil {
        fmt.Println(prettyJSON.String())
    } else {
      fmt.Println(string(body))
    }
  // TODO: Unmarshal JSON if needed
}

C++

#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/json.h>

using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace web::json;

pplx::task<void> UpdateTallyfyMemberRole(int userId, const utility::string_t& newRole)
{
    utility::string_t accessToken = U("YOUR_PERSONAL_ACCESS_TOKEN");
    utility::string_t orgId = U("YOUR_ORGANIZATION_ID");
    utility::string_t userIdStr = utility::conversions::to_string_t(std::to_string(userId));
    utility::string_t apiUrl = U("https://go.tallyfy.com/api/organizations/") + orgId + U("/users/") + userIdStr + U("/role");

    // Construct payload
    value payload = value::object();
    payload[U("role")] = value::string(newRole);

    http_client client(apiUrl);
    http_request request(methods::PUT);

    request.headers().add(U("Authorization"), U("Bearer ") + accessToken);
    request.headers().add(U("Accept"), U("application/json"));
    request.headers().add(U("X-Tallyfy-Client"), U("APIClient"));
    request.headers().set_content_type(U("application/json"));
    request.set_body(payload);

    return client.request(request).then([userId, newRole](http_response response)
    {
        return response.extract_json().then([response, userId, newRole](pplx::task<value> task)
        {
            try {
                value const & body = task.get();
                if (response.status_code() == status_codes::OK) {
                    std::wcout << L"Successfully updated role for member " << userId << L" to " << newRole << L":\n" << body.serialize() << std::endl;
                } else {
                    std::wcerr << L"Failed to update role for member " << userId << L". Status: " << response.status_code() << L"\nResponse: " << body.serialize() << std::endl;
                }
            } catch (const http_exception& e) {
                 std::wcerr << L"HTTP exception during update role: " << e.what() << std::endl;
            } catch (const std::exception& e) {
                std::wcerr << L"Exception during update role response handling: " << e.what() << std::endl;
            }
        });
    });
}

int main() {
    try {
        // Ensure the role string is valid ("admin", "standard", "light")
        UpdateTallyfyMemberRole(12345, U("light")).wait(); // Replace user ID
    } catch (const std::exception &e) {
        std::cerr << "Error in main: " << e.what() << std::endl;
    }
    return 0;
}
// Requires C++ REST SDK (Casablanca)

C#

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class TallyfyMemberRoleUpdater
{
    private static readonly HttpClient client = new HttpClient();

    public class RolePayload
    {
        public string Role { get; set; } // Required: "admin", "standard", or "light"
    }

    public static async Task UpdateMemberRoleAsync(int userId, string newRole)
    {
        var accessToken = Environment.GetEnvironmentVariable("TALLYFY_ACCESS_TOKEN") ?? "YOUR_PERSONAL_ACCESS_TOKEN";
        var orgId = Environment.GetEnvironmentVariable("TALLYFY_ORG_ID") ?? "YOUR_ORGANIZATION_ID";
        var apiUrl = $"https://go.tallyfy.com/api/organizations/{orgId}/users/{userId}/role";

        var payload = new RolePayload { Role = newRole };

        try
        {
            using var request = new HttpRequestMessage(HttpMethod.Put, apiUrl);
            request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
            request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
            request.Headers.Add("X-Tallyfy-Client", "APIClient");

            string jsonPayload = JsonSerializer.Serialize(payload);
            request.Content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");

            HttpResponseMessage response = await client.SendAsync(request);
            string responseBody = await response.Content.ReadAsStringAsync();

            if (response.IsSuccessStatusCode) // Expect 200 OK
            {
                Console.WriteLine($"Successfully updated role for member {userId} to {newRole}:");
                try {
                    using var doc = JsonDocument.Parse(responseBody);
                    Console.WriteLine(JsonSerializer.Serialize(doc.RootElement, new JsonSerializerOptions { WriteIndented = true }));
                } catch (JsonException) {
                    Console.WriteLine(responseBody);
                }
            }
            else
            {
                Console.WriteLine($"Failed to update role for member {userId}. Status: {response.StatusCode}");
                Console.WriteLine($"Response: {responseBody}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request Exception updating role for member {userId}: {e.Message}");
        }
        catch (JsonException jsonEx)
        {
             Console.WriteLine($"JSON Serialization Error: {jsonEx.Message}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"An unexpected error occurred: {ex.Message}");
        }
    }

    // Example Usage:
    // static async Task Main(string[] args)
    // {
    //     await UpdateMemberRoleAsync(12345, "admin"); // Replace user ID
    // }
}

Response

A successful request returns a 200 OK status code and a JSON object containing the member’s full profile, reflecting the updated user_role.

{
  "data": {
    "id": 12345,
    "email": "specific.user@example.com",
    "first_name": "Specific",
    "last_name": "User",
    "user_role": "light", // Role is updated
    // ... other user properties ...
    "last_updated": "2024-05-21T14:00:00Z" // Timestamp reflects the update
  }
}

If the user ID or role name is invalid, or you lack permission, an appropriate error status code (404, 403, 400, 422) will be returned.

---

Related articles

Members > Update member

A PUT endpoint that modifies organization member profiles by accepting JSON data containing updated fields and returning the complete updated profile upon success.

Members > Change the role of a member

A comprehensive guide for administrators to modify member roles between Administrator Standard and Light levels within Tallyfy by accessing organization settings and selecting new permissions based on job responsibilities.

Groups > Update group

The PUT endpoint allows updating a group’s details including name description members and guests while returning the modified group data upon successful completion with appropriate status codes.

Members > Get member

The GET endpoint retrieves detailed profile information of an organization member including their personal details roles permissions and optional related data like stats assets or groups based on the provided user ID.