Skip to main content

Groups

GET List of groups in organization with user and workspace assignments

https://api.track.toggl.com/api/v9/organizations/{organization_id}/groups

Returns list of groups in organization based on set of url parameters. List is sorted by name.

curl  https://api.track.toggl.com/api/v9/organizations/{organization_id}/groups \
-H "Content-Type: application/json" \
-u <email>:<password>

Parameters

Path

nametyperequireddescription
organization_idintegertrueNumeric ID of the organization

Query

nametyperequireddescription
namestringfalseReturns records where name contains this string
workspacestringfalseID of workspace. Returns groups assigned to this workspace

Response

200

NameTypeDescription
itemsArray of object-
items
NameTypeDescription
atstring-
group_idinteger-
namestring-
permissionsArray of string-
usersArray of object-
workspacesArray of integer-
users
NameTypeDescription
avatar_urlstring-
inactiveboolean-
joinedboolean-
namestring-
user_idinteger-

400

Invalid number ...

POST Create group

https://api.track.toggl.com/api/v9/organizations/{organization_id}/groups

Creates a group in the specified organization

curl -X POST https://api.track.toggl.com/api/v9/organizations/{organization_id}/groups \
-H "Content-Type: application/json" \
-d '\{"name":"string","users":[\{\}],"workspaces":[\{\}]\}' \
-u <email>:<password>

Parameters

Path

nametyperequireddescription
organization_idintegertrueNumeric ID of the organization.

Body

NameTypeDescription
namestringGroup name
usersArray of integerGroup users, optional
workspacesArray of integerGroup workspaces

Response

200

Returns the created group data.

NameTypeDescription
atstring-
group_idinteger-
namestring-
permissionsArray of string-
usersArray of object-
workspacesArray of integer-
users
NameTypeDescription
avatar_urlstring-
inactiveboolean-
joinedboolean-
namestring-
user_idinteger-

400

Possible error messages:

  • Invalid JSON input
  • Group name must be present
  • Group name too long, maximum length is 200
  • Name has already been taken
  • User {user} not exists in the organization {org}
  • Workspace {ws} not exists in the organization {org}

403

User does not have access to this resource

PUT Edit group

https://api.track.toggl.com/api/v9/organizations/{organization_id}/groups/{group_id}

Edits a group in the specified organization

curl -X PUT https://api.track.toggl.com/api/v9/organizations/{organization_id}/groups/{group_id} \
-H "Content-Type: application/json" \
-d '\{"name":"string","users":[\{\}],"workspaces":[\{\}]\}' \
-u <email>:<password>

Parameters

Path

nametyperequireddescription
organization_idintegertrueNumeric ID of the organization.
group_idintegertrueNumeric ID of the group.

Body

NameTypeDescription
namestringGroup name
usersArray of integerGroup users, optional
workspacesArray of integerGroup workspaces

Response

200

Returns the created group data.

NameTypeDescription
atstring-
group_idinteger-
namestring-
permissionsArray of string-
usersArray of object-
workspacesArray of integer-
users
NameTypeDescription
avatar_urlstring-
inactiveboolean-
joinedboolean-
namestring-
user_idinteger-

400

Possible error messages:

  • Invalid JSON input
  • Group name must be present
  • Group name too long, maximum length is 200
  • Name has already been taken
  • User {user} not exists in the organization {org}
  • Workspace {ws} not exists in the organization {org}

403

Forbidden

404

Invalid group ID.

DELETE Deletes group

https://api.track.toggl.com/api/v9/organizations/{organization_id}/groups/{group_id}

Deletes a group from the specified organization

curl -X DELETE https://api.track.toggl.com/api/v9/organizations/{organization_id}/groups/{group_id} \
-H "Content-Type: application/json" \
-u <email>:<password>

Parameters

Path

nametyperequireddescription
organization_idintegertrueNumeric ID of the organization.
group_idintegertrueNumeric ID of the group.

Response

200

OK

403

User does not have access to this resource

404

Invalid group ID.

PATCH Patch group

https://api.track.toggl.com/api/v9/organizations/{organization_id}/groups/{group_id}

Patches a group in the specified organization. Patches are applied individually and each patch is validated separately.

This endpoint supports only the following operation combinations:

  • Adding users: op="add", path="/users"
  • Removing users: op="remove", path="/users"
  • Adding workspaces: op="add", path="/workspaces"
  • Removing workspaces: op="remove", path="/workspaces"

Limitations:

  • Maximum 100 patches per request
  • Maximum 100 values (user IDs or workspace IDs) per patch operation
  • Scalar fields (e.g., group name) cannot be modified via PATCH; use PUT endpoint instead

Request body schema: Array of patch objects, where each object contains:

  • op (string): Operation type, must be "add" or "remove"
  • path (string): Target path, must be "/users" or "/workspaces"
  • value (array of integers): Array of user IDs or workspace IDs

Example request: [ {"op": "add", "path": "/users", "value": [123, 456]}, {"op": "remove", "path": "/workspaces", "value": [789]} ]

curl -X PATCH https://api.track.toggl.com/api/v9/organizations/{organization_id}/groups/{group_id} \
-H "Content-Type: application/json" \
-d '[\{"op":"string","path":"string","value":[\{\}]\}]' \
-u <email>:<password>

Parameters

Path

nametyperequireddescription
organization_idintegertrueNumeric ID of the organization.
group_idintegertrueNumeric ID of the group.

Body

NameTypeDescription
itemsArray of object-
items
NameTypeDescription
opstring-
pathstring-
valueArray of integer-

Response

200

Returns the result of the requested operations.

NameTypeDescription
failureArray of object-
successArray of object-
failure
NameTypeDescription
messagestring-
patchobject-
patch
NameTypeDescription
opstring-
pathstring-
valueArray of integer-
success
NameTypeDescription
opstring-
pathstring-
valueArray of integer-

400

Possible error messages:

  • Invalid JSON input
  • Unsupported operation (invalid 'op' or 'path', or unsupported combination)
  • Value not present, or too many per patch operation (empty 'value' array or more than 100 values)
  • Too many operations (more than 100 patches in request)
  • Unknown group at organization
  • User {id} not exists in the organization {id}
  • Workspace {id} not exists in the organization {id}

403

User does not have permission to manage user groups.

404

Invalid group ID.

GET List of groups in a workspace within an organization with user assignments.

https://api.track.toggl.com/api/v9/organizations/{organization_id}/workspaces/{workspace_id}/groups

Returns list of groups in a workspace based on set of url parameters. List is sorted by name.

curl  https://api.track.toggl.com/api/v9/organizations/{organization_id}/workspaces/{workspace_id}/groups \
-H "Content-Type: application/json" \
-u <email>:<password>

Parameters

Path

nametyperequireddescription
organization_idintegertrueNumeric ID of the organization
workspace_idintegertrueNumeric ID of the workspace within the organization

Response

200

NameTypeDescription
itemsArray of object-
items
NameTypeDescription
atstring-
group_idinteger-
namestring-
permissionsArray of string-
usersArray of object-
workspacesArray of integer-
users
NameTypeDescription
avatar_urlstring-
inactiveboolean-
joinedboolean-
namestring-
user_idinteger-

403

Forbidden

404

Resource can not be found

GET Get workspace project groups.

https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/project_groups

Get project groups for given workspace.

curl  https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/project_groups \
-H "Content-Type: application/json" \
-u <email>:<password>

Parameters

Path

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace

Query

nametyperequireddescription
project_idsstringtrueProject IDs separated by comma.

Response

200

NameTypeDescription
itemsArray of object-
items
NameTypeDescription
group_idinteger-
idinteger-
pidinteger-
widinteger-

403

User does not have access to this resource.

500

Internal Server Error

POST Adds group to project.

https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/project_groups

Adds group to project for given workspace.

curl -X POST https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/project_groups \
-H "Content-Type: application/json" \
-d '\{"group_id":"integer","project_id":"integer"\}' \
-u <email>:<password>

Parameters

Path

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace

Body

NameTypeDescription
group_idintegerGroup ID
project_idintegerProject ID

Response

200

Successful operation.

403

User does not have access to this resource.

500

Internal Server Error

DELETE Remove project group.

https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/project_groups/{project_group_id}

Remove project group for a given workspace.

curl -X DELETE https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/project_groups/{project_group_id} \
-H "Content-Type: application/json" \
-u <email>:<password>

Parameters

Path

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
project_group_idintegertrueNumeric ID of the project group

Response

200

Successful operation.

403

User does not have access to this resource.

500

Internal Server Error

© 2025 Toggl. All rights reserved.