Skip to main content

Organizations

POST Creates a new organization

https://api.track.toggl.com/api/v9/organizations

Creates a new organization with a single workspace and assigns current user as the organization owner

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

Parameters

Body

NameTypeDescription
namestringName of the organization
workspace_namestringName of the workspace

Response

200

Organization and workspace IDs

NameTypeDescription
idinteger-
namestring-
permissionsstring-
workspace_idinteger-
workspace_namestring-

400

Possible error messages:

  • Invalid JSON input
  • Field 'name' cannot be empty.
  • organization name too long, maximum length is 140
  • workspace name must contain non-space characters
  • workspace name must be provided
  • workspace name must not be longer than 140

403

User is not authorized to create an organization

GET Organization data

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

Returns organization name and current pricing plan

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

Parameters

Path

nametyperequireddescription
organization_idintegertrueNumeric ID of the organization

Response

200

NameTypeDescription
adminbooleanWhether the requester is an admin of the organization
atstringOrganization's last modification date
created_atstringOrganization's creation date
idintegerOrganization ID
is_multi_workspace_enabledbooleanIs true when the organization option is_multi_workspace_enabled is set
is_unifiedboolean-
max_data_retention_daysintegerHow far back free workspaces in this org can access data.
max_workspacesintegerMaximum number of workspaces allowed for the organization
namestringOrganization Name
ownerbooleanWhether the requester is a the owner of the organization
permissionsstring-
pricing_plan_enterprisebooleanThe subscription plan is an enterprise plan
pricing_plan_idintegerOrganization plan ID
pricing_plan_namestringThe subscription plan name the org is currently on. Free or any plan name coming from payment provider
suspended_atstringWhether the organization is currently suspended
trial_infoobject-
user_countintegerNumber of organization users
trial_info
NameTypeDescription
can_have_trialbooleanCanHaveInitialTrial is true if neither the organization nor the owner has never had a trial before
last_pricing_plan_idintegernull
next_payment_datestringnull
trialbooleanWhether the organization's subscription is currently on trial
trial_availablebooleanWhen a trial is available for this organization
trial_end_datestringnull

404

Possible error messages:

  • Invalid organization ID
  • User not part of organization

PUT Updates an existing organization

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

Updates an existing organization

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

Parameters

Path

nametyperequireddescription
organization_idintegertrueNumeric ID of the organization.

Body

NameTypeDescription
namestringName of the organization

Response

200

OK

400

Possible error messages:

  • Invalid JSON input
  • Invalid organization ID
  • At least one field is required
  • field 'name' cannot be empty
  • organization name too long, maximum length is 140

403

User is not authorized to update the organization

GET List of users in organization

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

Returns list of users in organization based on set of url parameters: Result is paginated. Pagination params are returned in headers

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

Parameters

Path

nametyperequireddescription
organization_idintegertrueNumeric ID of the organization

Query

nametyperequireddescription
filterstringfalseReturns records where name or email contains this string
active_statusstringfalseList of active inactive invited comma separated(if not present, all statuses)
only_adminsstringfalseIf true returns admins only
groupsstringfalseComma-separated list of groups ids, returns users belonging to these groups only
workspacesstringfalseComma-separated list of workspaces ids, returns users belonging to this workspaces only
pageintegerfalsePage number, default 1
per_pageintegerfalseNumber of items per page, default 50
sort_dirstringfalseValues 'asc' or 'desc', result is sorted on 'names' column, default 'asc'

Response

200

NameTypeDescription
itemsArray of object-
items
NameTypeDescription
adminbooleanDeprecated, to be removed. Use RoleID, or IsAdmin method if you must access this field.
avatar_urlstring-
can_edit_emailboolean-
emailstring-
groupsArray of object-
idinteger-
inactiveboolean-
invitation_codestring-
joinedboolean-
namestring-
organization_idinteger-
ownerbooleanDeprecated, to be removed. Use RoleID, or IsOwner method if you must access this field.
role_idinteger-
user_idinteger-
workspace_countinteger-
workspacesArray of object-
groups
NameTypeDescription
group_idinteger-
namestring-
workspaces
NameTypeDescription
adminbooleanDeprecated, to be removed. Use RoleID, or IsAdmin method if you must access this field.
costnumber-
default_currencystring-
groupsArray of object-
inactiveboolean-
ratenumber-
rolestringDeprecated, to be removed
role_idinteger-
working_hoursnumber-
workspace_idinteger-
workspace_namestring-
workspace_user_idinteger-
groups
NameTypeDescription
group_idinteger-
namestring-

400

Possible error messages:

  • Missing or invalid organization_id.
  • active_status parameter can contain only 'active', 'inactive' or 'invited'.
  • only_admins parameter can contain only 'true' or 'false'.
  • Invalid value sent for 'page'.
  • page parameter must contain values > 0.
  • Invalid value sent for 'per_page'.
  • per_page parameter must contain values > 0.
  • sort_dir parameter can contain only 'asc' or 'desc'.
  • Invalid value sent for 'groups'.
  • Invalid value sent for 'workspaces'.

403

User is not authorized to list the organization users

PATCH Apply changes in bulk to users in an organization

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

Apply changes in bulk to users in an organization (currently deletion only).

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

Parameters

Path

nametyperequireddescription
organization_idintegertrueNumeric ID of the organization

Body

NameTypeDescription
deleteArray of integerOrganization user IDs to be deleted

Response

200

OK

400

Possible error messages:

  • Missing or invalid organization_id
  • At least one organization user ID must be supplied.
  • Organization user IDs must be unique.
  • The following organization user IDs do not belong to this organization: '...'.
  • Cannot remove the paying user with organization user ID='...'.
  • Cannot remove the organization owner user with organization user ID='...'.

403

User is not authorized to delete the organization user

DELETE Leaves organization

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

Leaves organization, effectively delete user account in org and delete organization if it is last user

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

Parameters

Path

nametyperequireddescription
organization_idintegertrueNumeric ID of the organization

Response

200

Successful operation.

400

Possible error messages:

  • The user does not belong to the organization.
  • Cannot remove the paying user.
  • Cannot remove the organization owner.

403

User does not have access to this resource.

PUT Changes a single organization-user

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

Changes a single organization-user. Can affect the following values:

curl -X PUT https://api.track.toggl.com/api/v9/organizations/{organization_id}/users/{organization_user_id} \
-H "Content-Type: application/json" \
-d '\{"admin":"boolean","inactive":"boolean","labor_cost":"number","labor_cost_change_mode":"string","labour_cost":"integer","postedFields":[\{\}],"rate":"number","rate_change_mode":"string","role":"string","role_id":"integer","working_hours_in_minutes":"integer"\}' \
-u <email>:<password>

Parameters

Path

nametyperequireddescription
organization_idintegertrueNumeric ID of the organization

Body

NameTypeDescription
adminboolean-
inactiveboolean-
labor_costnumberCustom labor cost for project user
labor_cost_change_modestring-
labour_costintegerPaid feature -> DEPRECATED
postedFieldsArray of stringfor explicit NULL-s, add field name here
ratenumberPaid feature
rate_change_modestringPaid feature
rolestringAllowed inputs: "admin", "user", "projectlead" and "teamlead"
role_idinteger-
working_hours_in_minutesintegerPaid feature

Response

200

OK

400

Possible error messages:

  • Missing or invalid organization_id.
  • Invalid role_id.
  • Cannot use both admin flags and role_id.
  • User does not exist in the organization.
  • At least one field is required.
  • Field 'name' cannot be empty.
  • Missing e-mail.
  • Invalid e-mail: '...'
  • Email already exists.
  • Group '...' is not in Organization '...'.
  • Workspace '...' is not in Organization '...'.
  • Cannot remove admin privileges from owner.
  • Cannot deactivate owner.
  • Cannot remove admin privileges from paying user.
  • Cannot deactivate paying user.
  • User has multiple organizations.
  • Invalid organization role.
  • Invalid role ID: 1234.
  • Invalid workspace role with ID: 1234.

403

User is not authorized to update the organization user

404

Possible error messages:

  • Invalid organization user ID.
  • Failed to load user data.

GET Statistics for all workspaces in the organization

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

Returns map indexed by workspace ID where each map element contains workspace admins list, members count and groups count.

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

Response

200

Successful operation.

403

Forbidden

404

Resource can not be found

PUT Change assignments of users within a workspace.

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

Assign or remove users to/from a workspace or to/from groups belonging to said workspace.

curl -X PUT https://api.track.toggl.com/api/v9/organizations/{organization_id}/workspaces/{workspace_id}/assignments \
-H "Content-Type: application/json" \
-d '\{"group_id":"integer","joined":"boolean","operation":"string","user_id":"integer"\}' \
-u <email>:<password>

Parameters

Path

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

Body

NameTypeDescription
group_idinteger-
joinedboolean-
operationstring-
user_idinteger-

Response

200

OK

400

Possible error messages:

  • Invalid JSON input
  • Invalid organization ID.
  • Nothing to change.
  • Field operation can contain only 'add' or 'remove'.
  • Cannot send user_id and group_id in the same element.
  • One of user_id or group_id is required.
  • Invalid user_id.
  • Cannot remove workspace owner.
  • Cannot remove paying user.
  • Cannot remove organization admin.
  • Invalid group_id.
  • Invalid workspace ID.

403

Forbidden

© 2024 Toggl. All rights reserved.