Create group

Endpoint

POST /organizations/{org_id}/groups

This endpoint creates a new group 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
• Content-Type: application/json

Body (JSON)

The request body requires a JSON object defining the new group.

Refer to the #definitions/createGroupInput schema in Swagger. Key fields:

• name (string, required): The name of the group.
• description (string, optional): A description for the group.
• members (array of integers, optional): An array of User IDs for members to add to the group.
• guests (array of strings, optional): An array of email addresses for guests to add to the group.

Minimal Example Body:

{
  "name": "Project Alpha Team"
}

Example Body with Members/Guests:

{
  "name": "Onboarding Specialists",
  "description": "Team responsible for new client onboarding.",
  "members": [1001, 1005, 1008],
  "guests": ["client.liaison@partner.com"]
}

Code Samples

Javascript

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/groups`;

const groupData = {
  name: "Marketing Campaign Crew",
  description: "Cross-functional team for the Q3 campaign.",
  members: [1002, 1003],
  guests: ["freelancer@design.co"]
};

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: 'POST',
    headers: headers,
    body: JSON.stringify(groupData)
})
.then(response => {
    return response.json().then(data => {
        if (!response.ok) {
            console.error("Failed to create group:", data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return data;
    });
})
.then(data => {
    console.log('Successfully created group:');
    console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
    console.error('Error creating group:', 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',
    'Content-Type': 'application/json'
}

group_payload = {
    'name': 'Finance Approvers',
    'members': [1004, 1006]
}

response = None
try:
    response = requests.post(api_url, headers=headers, json=group_payload)
    response.raise_for_status()

    created_group = response.json()
    print('Successfully created group:')
    print(json.dumps(created_group, indent=4))

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred: {http_err}")
    if response is not None:
        print(f"Response Body: {response.text}")
except requests.exceptions.RequestException as req_err:
    print(f"Request failed: {req_err}")
except json.JSONDecodeError:
    print("Failed to decode JSON response")
    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;

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

        String jsonPayload = "{\"name\": \"Support Escalation Team\", \"members\": [1002, 1003]}";

        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")
                .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
                .build();

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

            if (response.statusCode() == 200 || response.statusCode() == 201) {
                System.out.println("Successfully created group:");
                System.out.println(response.body());
            } else {
                 System.err.println("Failed to create group. 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"
    "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" }
    apiUrl := fmt.Sprintf("https://go.tallyfy.com/api/organizations/%s/groups", orgId)

  groupData := map[string]interface{}{
    "name": "Go Development Team",
        "members": []int{1010, 1011},
        "guests": []string{"go.contractor@example.dev"},
  }

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

  client := &http.Client{Timeout: 15 * time.Second}
  req, err := http.NewRequest(http.MethodPost, apiUrl, bytes.NewBuffer(jsonData))
    if err != nil {
        fmt.Printf("Error creating request: %v\n", 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 request: %v\n", err)
        return
    }
  defer resp.Body.Close()

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

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

  fmt.Println("Successfully created group:")
    var prettyJSON bytes.Buffer
    if err := json.Indent(&prettyJSON, body, "", "  "); err == nil {
        fmt.Println(prettyJSON.String())
    } else {
      fmt.Println(string(body))
    }
}

C++

#include <iostream>
#include <string>
#include <vector>
#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> CreateTallyfyGroup(const utility::string_t& groupName,
                                  const std::vector<int>& memberIds,
                                  const std::vector<utility::string_t>& guestEmails)
{
    utility::string_t accessToken = U("YOUR_PERSONAL_ACCESS_TOKEN");
    utility::string_t orgId = U("YOUR_ORGANIZATION_ID");
    utility::string_t apiUrl = U("https://go.tallyfy.com/api/organizations/") + orgId + U("/groups");

    value payload = value::object();
    payload[U("name")] = value::string(groupName);

    if (!memberIds.empty()) {
        value membersArray = value::array(memberIds.size());
        for (size_t i = 0; i < memberIds.size(); ++i) {
            membersArray[i] = value::number(memberIds[i]);
        }
        payload[U("members")] = membersArray;
    }
     if (!guestEmails.empty()) {
        value guestsArray = value::array(guestEmails.size());
        for (size_t i = 0; i < guestEmails.size(); ++i) {
            guestsArray[i] = value::string(guestEmails[i]);
        }
        payload[U("guests")] = guestsArray;
    }

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

    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([](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 || response.status_code() == status_codes::Created) {
                    std::wcout << L"Successfully created group:\n" << body.serialize() << std::endl;
                } else {
                    std::wcerr << L"Failed to create group. Status: " << response.status_code() << L"\nResponse: " << body.serialize() << std::endl;
                }
            } catch (const http_exception& e) {
                 std::wcerr << L"HTTP exception during create group: " << e.what() << std::endl;
            } catch (const std::exception& e) {
                std::wcerr << L"Exception during create group response handling: " << e.what() << std::endl;
            }
        });
    });
}

int main() {
    try {
        std::vector<int> members = {1001, 1005};
        std::vector<utility::string_t> guests = {U("client.liaison@partner.com")};
        CreateTallyfyGroup(U("C++ Created Team"), members, guests).wait();
    } catch (const std::exception &e) {
        std::cerr << "Error in main: " << e.what() << std::endl;
    }
    return 0;
}

C#

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

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

    public class GroupPayload
    {
        public string Name { get; set; }
        public string Description { get; set; }
        public List<int> Members { get; set; }
        public List<string> Guests { get; set; }
    }

    public static async Task CreateGroupAsync(GroupPayload payload)
    {
        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}/groups";

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

            var options = new JsonSerializerOptions { IgnoreNullValues = true };
            string jsonPayload = JsonSerializer.Serialize(payload, options);
            request.Content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");

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

            if (response.IsSuccessStatusCode)
            {
                Console.WriteLine("Successfully created group:");
                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 create group. Status: {response.StatusCode}");
                Console.WriteLine($"Response: {responseBody}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request Exception: {e.Message}");
        }
         catch (JsonException jsonEx)
        {
             Console.WriteLine($"JSON Serialization Error: {jsonEx.Message}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"An unexpected error occurred: {ex.Message}");
        }
    }
}

Response

A successful request returns a 200 OK or 201 Created status code and a JSON object containing the details of the newly created group, including its assigned id.

{
  "data": {
    "id": "new_group_id_789",
    "name": "Onboarding Specialists",
    "description": "Team responsible for new client onboarding.",
    "logo": null,
    "members": [1001, 1005, 1008],
    "guests": ["client.liaison@partner.com"],
    "created_at": "2024-05-21T18:00:00Z",
    "updated_at": "2024-05-21T18:00:00Z",
    "deleted_at": null
  }
}

Make note of the returned id to manage this group later (get, update, delete).

---

Related articles

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.

Tags > Create tag

A POST endpoint that creates organization tags with specified title and color properties through multiple programming language examples including JavaScript Python Java and Go.

Guests > Create guest

The POST endpoint creates guest users in an organization by accepting JSON data with required email and optional fields like name and company details while returning the newly created guest’s information upon success.

Groups > List groups

The GET endpoint allows retrieving organization-specific groups with their details such as IDs names descriptions logos member lists and timestamps through authenticated API requests using various programming languages.