Skip to content
Tallyfy

Create group

Endpoint

POST /organizations/{org_id}/groups

This endpoint creates a new group within your Tallyfy 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

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

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": "YYYY-MM-DDTHH:MM:SSZ",
    "updated_at": "YYYY-MM-DDTHH:MM:SSZ",
    "deleted_at": null
  }
}

Make note of the returned id to manage this group later through Tallyfy’s API (get, update, delete).

Groups > Update group

This endpoint allows you to modify an existing group’s properties like name and description as well as its membership by sending a PUT request with the updated fields in JSON format where providing member or guest arrays will completely replace the existing lists rather than incrementally updating them.

Code Samples > Managing groups

API endpoints enable management of organizational groups through creating listing updating and deleting functionalities while organizing members and guests for various tasks.

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.

Tags > Create tag

This documentation explains how to create a new tag within an organization using a POST API endpoint by providing a required title and optional hex color code in the request body with code examples available in JavaScript Python Java Go C++ and C#.
Get in touch
About Tallyfy