Skip to main content

Workspaces

POST Create a new workspace.​

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

Create a workspace within an existing organization.

curl -X POST https://api.track.toggl.com/api/v9/organizations/{organization_id}/workspaces \
-H "Content-Type: application/json" \
-d '{"admins":["integer"],"default_currency":"string","default_hourly_rate":"number","initial_pricing_plan":"integer","name":"string","only_admins_may_create_projects":"boolean","only_admins_may_create_tags":"boolean","only_admins_see_billable_rates":"boolean","only_admins_see_team_dashboard":"boolean","projects_billable_by_default":"boolean","rate_change_mode":"string","reports_collapse":"boolean","rounding":"integer","rounding_minutes":"integer"}' \
-u <email>:<password>

Parameters​

Path​

nametyperequireddescription
organization_idintegertrueNumeric ID of the organization

Body​

nametypedescription
adminsArray of integerList of admins, optional
default_currencystringDefault currency, premium feature, optional, only for existing WS, will be 'USD' initially
default_hourly_ratenumberThe default hourly rate, premium feature, optional, only for existing WS, will be 0.0 initially
initial_pricing_planintegerThe subscription plan for the workspace, deprecated
namestringWorkspace name
only_admins_may_create_projectsbooleanOnly admins will be able to create projects, optional, only for existing WS, will be false initially
only_admins_may_create_tagsbooleanOnly admins will be able to create tags, optional, only for existing WS, will be false initially
only_admins_see_billable_ratesbooleanWhether only admins will be able to see billable rates, premium feature, optional, only for existing WS. Will be false initially
only_admins_see_team_dashboardbooleanOnly admins will be able to see the team dashboard, optional, only for existing WS, will be false initially
projects_billable_by_defaultbooleanWhether projects will be set as billable by default, premium feature, optional, only for existing WS. Will be true initially
rate_change_modestringThe rate change mode, premium feature, optional, only for existing WS. Can be "start-today", "override-current", "override-all"
reports_collapsebooleanWhether reports should be collapsed by default, optional, only for existing WS, will be true initially
roundingintegerDefault rounding, premium feature, optional, only for existing WS
rounding_minutesintegerDefault rounding in minutes, premium feature, optional, only for existing WS

Response​

200​

nametypedescription
adminboolean-
api_tokenstring-
atstring-
business_wsboolean-
csv_upload
nametypedescription
atstring-
log_idinteger-
-
default_currencystring-
default_hourly_ratenumber-
ical_enabledboolean-
ical_urlstring-
idinteger-
logo_urlstring-
namestring-
only_admins_may_create_projectsboolean-
only_admins_may_create_tagsboolean-
only_admins_see_billable_ratesboolean-
only_admins_see_team_dashboardboolean-
organization_idinteger-
premiumboolean-
profileinteger-
projects_billable_by_defaultboolean-
rate_last_updatedstring-
reports_collapseboolean-
roundinginteger-
rounding_minutesinteger-
server_deleted_atstring-
subscription
nametypedescription
auto_renewboolean-
card_detailsmodels.CardDetails-
company_idinteger-
contact_detailmodels.ContactDetail-
created_atstring-
currencystring-
customer_idinteger-
deleted_atstring-
last_pricing_plan_idinteger-
organization_idinteger-
payment_detailsmodels.PaymentDetail-
pricing_plan_idinteger-
renewal_atstring-
subscription_idinteger-
subscription_periodmodels.Period-
workspace_idinteger-
-
suspended_atstring-
te_constraints
nametypedescription
description_presentboolean-
project_presentboolean-
tag_presentboolean-
task_presentboolean-
time_entry_constraints_enabledboolean-
-

400​

Possible errors:

* JSON is not valid
* workspace name must contain non-space characters
* workspace name must not be nil
* workspace name must not be longer than 140
* another workspace with same name exists in organization
* user can have a maximum of 100 workspaces
* Multiple workspaces are not enabled in this organization.
* Organization {name} can have a maximum of {amount} workspaces
* User with id {id} does not exist.
* User {userID} not exists in the workspace.

402​

Possible errors:

* Must be a premium user to use default_hourly_rate
* restricting tag management to administrators requires a premium subscription
* Must be a premium user to use default_currency
* Must be a premium user to use rounding_minutes
* Must be a premium user to use only_admins_see_billable_rates
* Must be a premium user to use projects_billable_by_default
* Must be a premium user to use rounding

403​

Forbidden

404​

Possible errors:

* Organization not found/accessible
* Workspace not found/accessible
* organization owner not found

GET List of users who belong to the given workspace.​

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

Returns any users who belong to the workspace directly or through at least one group.

curl  https://api.track.toggl.com/api/v9/organizations/{organization_id}/workspaces/{workspace_id}/workspace_users \
-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​

Array of:

nametypedescription
activeboolean-
adminboolean-
atstring-
avatar_file_namestring-
emailstring-
group_ids-
idinteger-
inactiveboolean-
invitation_codestring-
invite_urlstring-
is_directboolean-
labour_costinteger-
namestring-
organization_adminboolean-
ratenumber-
rate_last_updatedstring-
timezonestring-
user_idinteger-
workspace_adminboolean-
workspace_idinteger-

403​

Forbidden

404​

Resource can not be found

PATCH Changes the users in a workspace.​

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

Changes the users in a workspace (currently deletion only).

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

Parameters​

Path​

nametyperequireddescription
organization_idintegertrueNumeric ID of the organization
workspace_idintegertrueNumeric ID of the workspace

Body​

nametypedescription
deleteArray of integerWorkspace user IDs to be deleted

Response​

200​

Successful operation.

400​

Possible error messages:

* JSON is not valid
* At least one workspace user ID must be supplied.
* Workspace user IDs must be unique"
* Wrong workspace user IDs

403​

Forbidden

POST Workspaces​

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

Change a workspace.

curl -X POST https://api.track.toggl.com/api/v9/workspaces \
-H "Content-Type: application/json" \
-d '{"admins":["integer"],"default_currency":"string","default_hourly_rate":"number","initial_pricing_plan":"integer","name":"string","only_admins_may_create_projects":"boolean","only_admins_may_create_tags":"boolean","only_admins_see_billable_rates":"boolean","only_admins_see_team_dashboard":"boolean","projects_billable_by_default":"boolean","rate_change_mode":"string","reports_collapse":"boolean","rounding":"integer","rounding_minutes":"integer"}' \
-u <email>:<password>

Parameters​

Body​

nametypedescription
adminsArray of integerList of admins, optional
default_currencystringDefault currency, premium feature, optional, only for existing WS, will be 'USD' initially
default_hourly_ratenumberThe default hourly rate, premium feature, optional, only for existing WS, will be 0.0 initially
initial_pricing_planintegerThe subscription plan for the workspace, deprecated
namestringWorkspace name
only_admins_may_create_projectsbooleanOnly admins will be able to create projects, optional, only for existing WS, will be false initially
only_admins_may_create_tagsbooleanOnly admins will be able to create tags, optional, only for existing WS, will be false initially
only_admins_see_billable_ratesbooleanWhether only admins will be able to see billable rates, premium feature, optional, only for existing WS. Will be false initially
only_admins_see_team_dashboardbooleanOnly admins will be able to see the team dashboard, optional, only for existing WS, will be false initially
projects_billable_by_defaultbooleanWhether projects will be set as billable by default, premium feature, optional, only for existing WS. Will be true initially
rate_change_modestringThe rate change mode, premium feature, optional, only for existing WS. Can be "start-today", "override-current", "override-all"
reports_collapsebooleanWhether reports should be collapsed by default, optional, only for existing WS, will be true initially
roundingintegerDefault rounding, premium feature, optional, only for existing WS
rounding_minutesintegerDefault rounding in minutes, premium feature, optional, only for existing WS

Response​

200​

nametypedescription
adminboolean-
api_tokenstring-
atstring-
business_wsboolean-
csv_upload
nametypedescription
atstring-
log_idinteger-
-
default_currencystring-
default_hourly_ratenumber-
ical_enabledboolean-
ical_urlstring-
idinteger-
logo_urlstring-
namestring-
only_admins_may_create_projectsboolean-
only_admins_may_create_tagsboolean-
only_admins_see_billable_ratesboolean-
only_admins_see_team_dashboardboolean-
organization_idinteger-
premiumboolean-
profileinteger-
projects_billable_by_defaultboolean-
rate_last_updatedstring-
reports_collapseboolean-
roundinginteger-
rounding_minutesinteger-
server_deleted_atstring-
subscription
nametypedescription
auto_renewboolean-
card_detailsmodels.CardDetails-
company_idinteger-
contact_detailmodels.ContactDetail-
created_atstring-
currencystring-
customer_idinteger-
deleted_atstring-
last_pricing_plan_idinteger-
organization_idinteger-
payment_detailsmodels.PaymentDetail-
pricing_plan_idinteger-
renewal_atstring-
subscription_idinteger-
subscription_periodmodels.Period-
workspace_idinteger-
-
suspended_atstring-
te_constraints
nametypedescription
description_presentboolean-
project_presentboolean-
tag_presentboolean-
task_presentboolean-
time_entry_constraints_enabledboolean-
-

403​

User does not have access to this resource.

500​

Internal Server Error

GET Get single workspace​

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

Get information of single workspace.

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

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric Workspace ID

Response​

200​

nametypedescription
adminboolean-
api_tokenstring-
atstring-
business_wsboolean-
csv_upload
nametypedescription
atstring-
log_idinteger-
-
default_currencystring-
default_hourly_ratenumber-
ical_enabledboolean-
ical_urlstring-
idinteger-
logo_urlstring-
namestring-
only_admins_may_create_projectsboolean-
only_admins_may_create_tagsboolean-
only_admins_see_billable_ratesboolean-
only_admins_see_team_dashboardboolean-
organization_idinteger-
premiumboolean-
profileinteger-
projects_billable_by_defaultboolean-
rate_last_updatedstring-
reports_collapseboolean-
roundinginteger-
rounding_minutesinteger-
server_deleted_atstring-
subscription
nametypedescription
auto_renewboolean-
card_detailsmodels.CardDetails-
company_idinteger-
contact_detailmodels.ContactDetail-
created_atstring-
currencystring-
customer_idinteger-
deleted_atstring-
last_pricing_plan_idinteger-
organization_idinteger-
payment_detailsmodels.PaymentDetail-
pricing_plan_idinteger-
renewal_atstring-
subscription_idinteger-
subscription_periodmodels.Period-
workspace_idinteger-
-
suspended_atstring-
te_constraints
nametypedescription
description_presentboolean-
project_presentboolean-
tag_presentboolean-
task_presentboolean-
time_entry_constraints_enabledboolean-
-

403​

User does not have access to this resource.

500​

Internal Server Error

PUT Update workspace​

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

Update a specific workspace.

curl -X PUT https://api.track.toggl.com/api/v9/workspaces/{workspace_id} \
-H "Content-Type: application/json" \
-d '{"admins":["integer"],"default_currency":"string","default_hourly_rate":"number","initial_pricing_plan":"integer","name":"string","only_admins_may_create_projects":"boolean","only_admins_may_create_tags":"boolean","only_admins_see_billable_rates":"boolean","only_admins_see_team_dashboard":"boolean","projects_billable_by_default":"boolean","rate_change_mode":"string","reports_collapse":"boolean","rounding":"integer","rounding_minutes":"integer"}' \
-u <email>:<password>

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric Workspace ID

Body​

nametypedescription
adminsArray of integerList of admins, optional
default_currencystringDefault currency, premium feature, optional, only for existing WS, will be 'USD' initially
default_hourly_ratenumberThe default hourly rate, premium feature, optional, only for existing WS, will be 0.0 initially
initial_pricing_planintegerThe subscription plan for the workspace, deprecated
namestringWorkspace name
only_admins_may_create_projectsbooleanOnly admins will be able to create projects, optional, only for existing WS, will be false initially
only_admins_may_create_tagsbooleanOnly admins will be able to create tags, optional, only for existing WS, will be false initially
only_admins_see_billable_ratesbooleanWhether only admins will be able to see billable rates, premium feature, optional, only for existing WS. Will be false initially
only_admins_see_team_dashboardbooleanOnly admins will be able to see the team dashboard, optional, only for existing WS, will be false initially
projects_billable_by_defaultbooleanWhether projects will be set as billable by default, premium feature, optional, only for existing WS. Will be true initially
rate_change_modestringThe rate change mode, premium feature, optional, only for existing WS. Can be "start-today", "override-current", "override-all"
reports_collapsebooleanWhether reports should be collapsed by default, optional, only for existing WS, will be true initially
roundingintegerDefault rounding, premium feature, optional, only for existing WS
rounding_minutesintegerDefault rounding in minutes, premium feature, optional, only for existing WS

Response​

200​

nametypedescription
adminboolean-
api_tokenstring-
atstring-
business_wsboolean-
csv_upload
nametypedescription
atstring-
log_idinteger-
-
default_currencystring-
default_hourly_ratenumber-
ical_enabledboolean-
ical_urlstring-
idinteger-
logo_urlstring-
namestring-
only_admins_may_create_projectsboolean-
only_admins_may_create_tagsboolean-
only_admins_see_billable_ratesboolean-
only_admins_see_team_dashboardboolean-
organization_idinteger-
premiumboolean-
profileinteger-
projects_billable_by_defaultboolean-
rate_last_updatedstring-
reports_collapseboolean-
roundinginteger-
rounding_minutesinteger-
server_deleted_atstring-
subscription
nametypedescription
auto_renewboolean-
card_detailsmodels.CardDetails-
company_idinteger-
contact_detailmodels.ContactDetail-
created_atstring-
currencystring-
customer_idinteger-
deleted_atstring-
last_pricing_plan_idinteger-
organization_idinteger-
payment_detailsmodels.PaymentDetail-
pricing_plan_idinteger-
renewal_atstring-
subscription_idinteger-
subscription_periodmodels.Period-
workspace_idinteger-
-
suspended_atstring-
te_constraints
nametypedescription
description_presentboolean-
project_presentboolean-
tag_presentboolean-
task_presentboolean-
time_entry_constraints_enabledboolean-
-

403​

User does not have access to this resource.

500​

Internal Server Error

POST Alerts​

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

Handles POST alert requests.

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

Response​

200​

nametypedescription
errorsArray of
nametypedescription
codestring-
messagestring-
-
idinteger-
object_typeinteger-
project_idinteger-
receiver_groupsstring-
receiver_rolesstring-
receiver_usersstring-
receiversinteger-
source_kindstring-
thresholdinteger-
threshold_typestring-
thresholdsstringusing pq types is a workaround to enable reading postgres arrays into go types we should wrap these pq types to avoid polluting our domain
widinteger-

400​

Possible errors:

* invalid workspace ID
* source kind can't be blank
* project can't be blank
* project not supported for this source kind
* threshold type can't be blank
* thresholds can't be blank
* receivers can't be blank
* alert type out of range
* receiver type out of range
* threshold out of range
* source kind out of range
* threshold type out of range
* receiver role out of range

500​

Internal Server Error

DELETE Alerts​

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

Handles DELETE alert requests.

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

Response​

200​

Successful operation.

403​

Alert not found or not accessible

500​

Internal Server Error

GET Workspace statistics​

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

Returns workspace admins list, members count and groups count

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

Response​

200​

nametypedescription
adminsArray of
nametypedescription
namestring-
user_idinteger-
-
groups_countinteger-
members_countinteger-

403​

User does not have access to this resource.

500​

Internal Server Error

GET Get workspace time entry constraints​

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

Get the time entry constraints for a given workspace.

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

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace

Response​

200​

nametypedescription
description_presentboolean-
project_presentboolean-
tag_presentboolean-
task_presentboolean-
time_entry_constraints_enabledboolean-

400​

Workspace not found

403​

User does not have access to this resource.

500​

Internal Server Error

GET TrackReminders​

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

Returns a list of track reminders.

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

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace

Response​

200​

Returns a list of track reminders.

Array of:

nametypedescription
created_atstringReminder creation time
frequencyintegerFrequency of the reminder in days, should be either 1 or 7
group_idsArray of integerGroups IDs to send the reminder to
reminder_idintegerReminder ID
thresholdintegerThreshold is the number of hours after which the reminder will be sent
user_idsArray of integerUser IDs to send the reminder to
workspace_idintegerWorkspace ID

403​

User does not have access to this resource.

500​

Internal Server Error

POST TrackReminders​

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

Creates a workspace tracking reminder.

curl -X POST https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/track_reminders \
-H "Content-Type: application/json" \
-d '{"frequency":"integer","group_ids":["integer"],"threshold":"number","user_ids":["integer"]}' \
-u <email>:<password>

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace

Body​

nametypedescription
frequencyintegerFrequency of the reminder in days, should be either 1 or 7
group_idsArray of integerGroup IDs to send the reminder to, can be omitted if user_ids is provided
thresholdnumberThreshold is the number of hours after which the reminder will be sent
user_idsArray of integerUser IDs to send the reminder to, can be omitted if group_ids is provided

Response​

200​

Creates a workspace tracking reminder.
nametypedescription
created_atstringReminder creation time
frequencyintegerFrequency of the reminder in days, should be either 1 or 7
group_idsArray of integerGroups IDs to send the reminder to
reminder_idintegerReminder ID
thresholdintegerThreshold is the number of hours after which the reminder will be sent
user_idsArray of integerUser IDs to send the reminder to
workspace_idintegerWorkspace ID

403​

User does not have access to this resource.

500​

Internal Server Error

PUT TrackReminder​

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

Updates a workspace tracking reminder.

curl -X PUT https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/track_reminders/{reminder_id} \
-H "Content-Type: application/json" \
-d '{"frequency":"integer","group_ids":["integer"],"threshold":"number","user_ids":["integer"]}' \
-u <email>:<password>

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
reminder_idintegertrueReminder ID.

Body​

nametypedescription
frequencyintegerFrequency of the reminder in days, should be either 1 or 7
group_idsArray of integerGroup IDs to send the reminder to, can be omitted if user_ids is provided
thresholdnumberThreshold is the number of hours after which the reminder will be sent
user_idsArray of integerUser IDs to send the reminder to, can be omitted if group_ids is provided

Response​

200​

Updates a workspace tracking reminder.
nametypedescription
created_atstringReminder creation time
frequencyintegerFrequency of the reminder in days, should be either 1 or 7
group_idsArray of integerGroups IDs to send the reminder to
reminder_idintegerReminder ID
thresholdintegerThreshold is the number of hours after which the reminder will be sent
user_idsArray of integerUser IDs to send the reminder to
workspace_idintegerWorkspace ID

403​

User does not have access to this resource.

500​

Internal Server Error

DELETE TrackReminder​

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

Deletes a workspace tracking reminder.

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

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
reminder_idintegertrueReminder ID.

Response​

200​

Returns only status code.

403​

User does not have access to this resource.

500​

Internal Server Error

GET Get workspace users​

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

List all users for a given workspace.

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

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace

Response​

200​

Array of:

nametypedescription
activeboolean-
adminboolean-
atstring-
avatar_file_namestring-
emailstring-
group_ids-
idinteger-
inactiveboolean-
invitation_codestring-
invite_urlstring-
labour_costinteger-
namestring-
ratenumber-
rate_last_updatedstring-
timezonestring-
uidinteger-
widinteger-

403​

User does not have access to this resource.

500​

Internal Server Error

PUT Update workspace user​

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

Update the data for a user in a given workspace.

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

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
user_idintegertrueNumeric ID of the user

Response​

200​

Successful operation.

400​

Bad Request

403​

User does not have access to this resource.

404​

Not Found

500​

Internal Server Error

POST Change a lost password​

https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/users/{user_id}/lost_password

Request a change password action

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

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
user_idintegertrueNumeric ID of the user

Response​

200​

The reset password URL
nametypedescription
urlstring-

400​

Possible error messages:

* Workspace not found
* User not found
* Workspace needs to have the Edit team members profile feature enabled

403​

User does not have access to this resource.

404​

Possible error messages:

* Workspace not found
* User not found

500​

Internal Server Error

PUT Update workspace-user​

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

Update the data for a workspace_user in a given workspace.

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