List groups

Endpoint

GET /organizations/{org_id}/groups

This endpoint retrieves a list of groups defined within the specified organization.

Request

Replace {org_id} with your Organization ID.

Headers

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

Query parameters (optional)

• with (string): Include additional data, e.g., assets (for group logo).
• Pagination parameters might be available.

Code samples

Javascript

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';

const queryParams = '?with=assets'; // Example: include group logos if available
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/groups${queryParams}`;

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

fetch(apiUrl, {
    method: 'GET',
    headers: headers
})
.then(response => {
     return response.json().then(data => { // Attempt to parse JSON regardless of status
        if (!response.ok) {
            console.error("Failed to list groups:", data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return data; // Pass successful data along
    });
})
.then(data => {
    console.log('Successfully listed groups:');
    console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
    console.error('Error listing groups:', 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')
api_url = f'https://go.tallyfy.com/api/organizations/{org_id}/groups'

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

# Optional: Add query parameters
params = {
    'with': 'assets' # Example: include group logos if available
}

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

    groups_data = response.json()
    print('Successfully listed groups:')
    print(json.dumps(groups_data, indent=4))

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred listing groups: {http_err}")
    if response is not None:
        print(f"Response Body: {response.text}")
except requests.exceptions.RequestException as req_err:
    print(f"Request failed listing groups: {req_err}")
except json.JSONDecodeError:
    print("Failed to decode JSON response when listing groups")
    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.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.Map;
import java.util.stream.Collectors;

public class ListGroups {
    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");
        String baseUrl = "https://go.tallyfy.com/api/organizations/" + orgId + "/groups";

        // Optional: Add query parameters
        Map<String, String> queryParamsMap = Map.of("with", "assets");
        String queryParamsString = queryParamsMap.entrySet().stream()
            .map(entry -> URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8) + "=" + URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8))
            .collect(Collectors.joining("&", "?", ""));

        String apiUrl = baseUrl + (queryParamsMap.isEmpty() ? "" : queryParamsString);

        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")
                .GET()
                .build();

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

            if (response.statusCode() == 200) {
                System.out.println("Successfully listed groups:");
                System.out.println(response.body());
                // TODO: Consider parsing JSON using Jackson/Gson
            } else {
                System.err.println("Failed to list groups. 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"
  "net/url"
  "os"
    "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" }
    baseURL := fmt.Sprintf("https://go.tallyfy.com/api/organizations/%s/groups", orgId)

    // Optional: Add query parameters
    queryParams := url.Values{}
    queryParams.Add("with", "assets") // Example: include group logos

    apiUrl := baseURL + "?" + queryParams.Encode()

  client := &http.Client{Timeout: 10 * time.Second}
  req, err := http.NewRequest("GET", apiUrl, nil)
    if err != nil {
    fmt.Printf("Error creating list groups request: %v\n", err)
    return
  }

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

  resp, err := client.Do(req)
    if err != nil {
    fmt.Printf("Error executing list groups request: %v\n", err)
    return
  }
  defer resp.Body.Close()

  body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
    fmt.Printf("Error reading list groups response body: %v\n", err)
    return
  }

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

  fmt.Println("Successfully listed groups:")
    // 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 from body into a slice of structs 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> ListTallyfyGroups()
{
    utility::string_t accessToken = U("YOUR_PERSONAL_ACCESS_TOKEN");
    utility::string_t orgId = U("YOUR_ORGANIZATION_ID");

    uri_builder builder(U("https://go.tallyfy.com/api/organizations/"));
    builder.append_path(orgId);
    builder.append_path(U("groups"));
    builder.append_query(U("with"), U("assets")); // Example query parameter
    utility::string_t apiUrl = builder.to_string();

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

    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"));

    return client.request(request).then([](http_response response)
    {
        return response.extract_json().then([response](pplx::task<value> task)
        {
            try {
                value const & body = task.get();
                if (response.status_code() == status_codes::OK) {
                    std::wcout << L"Successfully listed groups:\n" << body.serialize() << std::endl;
                    // Access data: body[U("data")].as_array()
                } else {
                    std::wcerr << L"Failed to list groups. Status: " << response.status_code() << L"\nResponse: " << body.serialize() << std::endl;
                }
            } catch (const http_exception& e) {
                 std::wcerr << L"HTTP exception during list groups: " << e.what() << std::endl;
            } catch (const std::exception& e) {
                std::wcerr << L"Exception during list groups response handling: " << e.what() << std::endl;
            }
        });
    });
}

int main() {
    try {
        ListTallyfyGroups().wait();
    } 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.Threading.Tasks;
using System.Text.Json;

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

    public static async Task ListGroupsAsync()
    {
        var accessToken = Environment.GetEnvironmentVariable("TALLYFY_ACCESS_TOKEN") ?? "YOUR_PERSONAL_ACCESS_TOKEN";
        var orgId = Environment.GetEnvironmentVariable("TALLYFY_ORG_ID") ?? "YOUR_ORGANIZATION_ID";

        // Build URL with query parameters
        var query = System.Web.HttpUtility.ParseQueryString(string.Empty);
        query["with"] = "assets"; // Example
        string queryString = query.ToString();
        var apiUrl = $"https://go.tallyfy.com/api/organizations/{orgId}/groups?{queryString}";

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

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

            if (response.IsSuccessStatusCode)
            {
                Console.WriteLine("Successfully listed groups:");
                // Pretty print JSON
                try {
                    using var doc = JsonDocument.Parse(responseBody);
                    Console.WriteLine(JsonSerializer.Serialize(doc.RootElement, new JsonSerializerOptions { WriteIndented = true }));
                    // Access data: foreach (var groupElement in doc.RootElement.GetProperty("data").EnumerateArray()) { ... }
                } catch (JsonException) {
                    Console.WriteLine(responseBody); // Print raw if not valid JSON
                }
            }
            else
            {
                Console.WriteLine($"Failed to list groups. Status: {response.StatusCode}");
                Console.WriteLine($"Response: {responseBody}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request Exception listing groups: {e.Message}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"An unexpected error occurred: {ex.Message}");
        }
    }

    // Example Usage:
    // static async Task Main(string[] args)
    // {
    //     await ListGroupsAsync();
    // }
}

Response

A successful request returns a 200 OK status code and a JSON object containing a data array. Each element represents a group.

{
  "data": [
    {
      "id": "group_id_abc123", // Unique group ID
      "name": "Sales Team",
      "description": "Handles all sales inquiries.",
      "logo": null, // Or URL if logo uploaded and requested with 'with=assets'
      "members": [1001, 1005], // Array of member user IDs
      "guests": ["client.a@example.com"], // Array of guest emails
      "created_at": "2023-03-10T09:00:00Z",
      "updated_at": "2024-04-20T10:00:00Z",
      "deleted_at": null
    },
    {
      "id": "group_id_def456",
      "name": "Support Tier 1",
      // ... other group details ...
    }
  ]
  // Potential meta object for pagination
}

---

Related articles

Groups > Get group

The GET endpoint allows retrieving detailed information about a specific group within an organization using its unique ID through authenticated API requests with code examples in multiple programming languages.

Members > List members

A comprehensive API endpoint documentation for retrieving organization members through various programming languages including authentication headers optional query parameters and response structure with sample code snippets.

Tags > List tags

The GET endpoint allows retrieval of organizational tags with optional filtering and sorting capabilities returning tag details such as ID title color and usage statistics through authenticated API requests.

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.