Create group

Endpoint

POST /organizations/{org_id}/groups

Creates a new group in your Tallyfy organization.

Request

Replace {org_id} with your actual Organization ID.

Headers

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

Body (JSON)

Field	Type	Required	Description
name	string	Yes	Group name (max 200 chars, must be unique in the org)
description	string	Yes	A description for the group
members	array of integers	No	User IDs to add as members
guests	array of strings	No	Email addresses for guests to add

Example body:

{
  "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 marketing initiatives.",
  members: [1002, 1003],
  guests: ["freelancer@design.co"]
};

const response = await fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Accept': 'application/json',
    'X-Tallyfy-Client': 'APIClient',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(groupData)
});

const data = await response.json();
if (!response.ok) {
  console.error("Failed to create group:", data);
} else {
  console.log('Created group:', JSON.stringify(data, null, 2));
}

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',
    'description': 'Team handling finance approval workflows.',
    'members': [1004, 1006]
}

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

print(json.dumps(response.json(), indent=4))

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class CreateGroup {
    public static void main(String[] args) throws Exception {
        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",
             "description": "Handles escalated support tickets.",
             "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();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}

Go

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io"
  "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",
    "description": "Backend engineers working in Go.",
    "members":     []int{1010, 1011},
    "guests":      []string{"go.contractor@example.dev"},
  }

  jsonData, _ := json.Marshal(groupData)
  client := &http.Client{Timeout: 15 * time.Second}
  req, _ := http.NewRequest(http.MethodPost, apiUrl, bytes.NewBuffer(jsonData))

  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("Request failed: %v\n", err); return }
  defer resp.Body.Close()

  body, _ := io.ReadAll(resp.Body)
  fmt.Printf("Status: %d\n%s\n", resp.StatusCode, 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;

int main() {
    auto accessToken = U("YOUR_PERSONAL_ACCESS_TOKEN");
    auto orgId = U("YOUR_ORGANIZATION_ID");
    auto apiUrl = U("https://go.tallyfy.com/api/organizations/") + orgId + U("/groups");

    value payload = value::object();
    payload[U("name")] = value::string(U("C++ Created Team"));
    payload[U("description")] = value::string(U("Team created via C++ client."));
    value membersArray = value::array(2);
    membersArray[0] = value::number(1001);
    membersArray[1] = value::number(1005);
    payload[U("members")] = membersArray;

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

    client.request(request).then([](http_response response) {
        return response.extract_json();
    }).then([](value body) {
        std::wcout << body.serialize() << std::endl;
    }).wait();

    return 0;
}

C#

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

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

using var client = new HttpClient();
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 payload = new {
    name = "Onboarding Specialists",
    description = "Team responsible for new client onboarding.",
    members = new[] { 1001, 1005, 1008 },
    guests = new[] { "client.liaison@partner.com" }
};

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

var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine($"Status: {response.StatusCode}");
Console.WriteLine(body);

Response

A successful request returns a 201 Created status. The response JSON wraps the new group inside a data object.

{
  "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": "2025-06-10T14:30:00.000Z",
    "last_updated": "2025-06-10T14:30:00.000Z"
  }
}

Save the returned id — you’ll need it to get, update, or delete this group later.

---

Related articles

Groups > Update group

Tallyfy’s PUT endpoint for groups lets you update a group’s name and description or fully replace its member and guest lists by sending user IDs and email arrays to /organizations/[org_id]/groups/[group_id] with code samples in JavaScript and Python and Java and Go and C++ and C#.

Code Samples > Managing groups

API endpoints let you create, list, get, update, and delete groups that organize members and guests for task and process assignment.

Groups > Get group

Retrieve details of a specific group in your organization by its ID using a GET request with code examples in multiple languages.

Tags > Create tag

Create a new tag in a Tallyfy organization using the POST API endpoint with a required title and optional hex color code, with examples in JavaScript, Python, Java, Go, C++, and C#.

Was this helpful?

YesNo