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

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_chargifyboolean-
is_multi_workspace_enabledbooleanIs true when the organization option is_multi_workspace_enabled is set
is_unifiedboolean-
max_workspacesintegerMaximum number of workspaces allowed for the organization
namestringOrganization Name
ownerbooleanWhether the requester is a the owner of the organization
payment_methodsstringOrganization's subscription payment methods. Omitted if empty.
pricing_plan_idintegerOrganization plan ID
server_deleted_atstring | nullOrganization's delete date
suspended_atstringWhether the organization is currently suspended
trial_info
nametypedescription
last_pricing_plan_idinteger | nullWhat was the previous plan before the trial
next_payment_datestring | nullWhen the trial payment is due
trialbooleanWhether the organization's subscription is currently on trial
trial_availablebooleanWhen a trial is available for this organization
trial_end_datestring | nullWhen the trial ends
-
user_countintegerNumber of organization users

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

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

Array of:

nametypedescription
adminboolean-
avatar_urlstring-
can_edit_emailboolean-
emailstring-
groupsArray of
nametypedescription
group_idinteger-
namestring-
-
idinteger-
inactiveboolean-
invitation_codestring-
joinedboolean-
namestring-
ownerboolean-
user_idinteger-
workspacesArray of
nametypedescription
adminboolean-
namestring-
workspace_idinteger-
-

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

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":["integer"]}' \
-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

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","labour_cost":"integer","postedFields":["string"],"rate":"number","rate_change_mode":"string"}' \
-u <email>:<password>

Parameters

Path

nametyperequireddescription
organization_idintegertrueNumeric ID of the organization

Body

nametypedescription
adminboolean-
inactiveboolean-
labour_costinteger-
postedFieldsArray of stringEnd pro features
ratenumberPro features
rate_change_modestring-

Response

200

OK

400

Possible error messages:

* Missing or invalid organization_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.

403

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.
* Invalid group_id.
* Invalid workspace ID.

403

Forbidden
© 2023 Toggl. All rights reserved.