Skip to main content

Projects

GET Get workspace projects users​

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

List all projects users for a given workspace.

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

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace

Query​

nametyperequireddescription
project_idsstringfalseNumeric IDs of projects, comma-separated
with_group_membersbooleanfalseInclude group members

Response​

200​

Array of:

nametypedescription
atstringWhen was last modified
gidintegerGroup ID, legacy field
group_idintegerGroup ID
idintegerProject User ID
labour_costintegerLabour cost for this project user
managerbooleanWhether the user is manager of the project
project_idintegerProject ID
ratenumber | nullCustom rate for project user
rate_last_updatedstringDate for rate last updated
user_idintegerUser ID
workspace_idintegerWorkspace ID

400​

Possible error messages:

* Workspace not found
* project_ids cannot exceed 200 elements.

403​

User does not have access to this resource.

500​

Internal Server Error

POST Add an user into workspace projects users​

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

Include a project user for a given workspace.

curl -X POST https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/project_users \
-H "Content-Type: application/json" \
-d '{"labour_cost":"integer","manager":"boolean","project_id":"integer","rate":"number","rate_change_mode":"string","use_last_labour_cost":"boolean","user_id":"integer"}' \
-u <email>:<password>

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace

Body​

nametypedescription
labour_costintegerLabour cost for this project user
managerbooleanWhether the user will be manager of the project
project_idintegerProject ID
ratenumberRate for this project user
rate_change_modestringRate change mode for this project user. Can be "start-today", "override-current", "override-all"
use_last_labour_costbooleanWhether the last labour cost should be applied or not, default false
user_idintegerUser ID

Response​

200​

nametypedescription
atstringWhen was last modified
gidintegerGroup ID, legacy field
group_idintegerGroup ID
idintegerProject User ID
labour_costintegerLabour cost for this project user
managerbooleanWhether the user is manager of the project
project_idintegerProject ID
ratenumber | nullCustom rate for project user
rate_last_updatedstringDate for rate last updated
user_idintegerUser ID
workspace_idintegerWorkspace ID

400​

Possible error messages:

* Workspace not found
* Invalid project_id
* Invalid user_id
<* Project user already exists

403​

User does not have access to this resource.

500​

Internal Server Error

PATCH Patch project users from workspace​

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

Patch a list of project users for a given workspace.

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

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace

Query​

nametyperequireddescription
project_user_ids[]integertrueNumeric IDs of the project users

Response​

200​

nametypedescription
failureArray of
nametypedescription
idintegerOrganization user ID
messagestringFound error message
List of found errors
successArray of integerList of org user IDs that were successfully patched

400​

Possible error messages:

* Invalid value as user IDs
* No patchable fields defined
* PATCH expects at least one ID
* PATCH request is limited to %d entries at once
* Invalid op:
* Invalid path format:
* Path not found:
* Operation not supported ({patch_operation} {patch_path})
* Invalid path
* /manager expects a boolean
* /labour_cost expects an int64 or null
* /rate expects an float64 or null
* Operation not supported (add /labour_cost)
* Operation not supported (add /rate)
* Operation not supported (add /manager)

403​

User does not have access to this resource.

500​

Internal Server Error

PUT Update an user into workspace projects users​

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

Update the data for a project user for a given workspace.

curl -X PUT https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/project_users/{project_user_id} \
-H "Content-Type: application/json" \
-d '{"labour_cost":"integer","manager":"boolean","rate":"number","rate_change_mode":"string"}' \
-u <email>:<password>

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
project_user_idintegertrueNumeric ID of the project user

Body​

nametypedescription
labour_costintegerLabour cost for this project user
managerbooleanWhether the user will be manager of the project
ratenumberRate for this project user
rate_change_modestringRate change mode for this project user. Can be "start-today", "override-current", "override-all"

Response​

200​

nametypedescription
atstringWhen was last modified
gidintegerGroup ID, legacy field
group_idintegerGroup ID
idintegerProject User ID
labour_costintegerLabour cost for this project user
managerbooleanWhether the user is manager of the project
project_idintegerProject ID
ratenumber | nullCustom rate for project user
rate_last_updatedstringDate for rate last updated
user_idintegerUser ID
workspace_idintegerWorkspace ID

400​

Possible error messages:

* Workspace not found
* Missing data
* Invalid project_id
* Invalid user_id

403​

User does not have access to this resource.

500​

Internal Server Error

DELETE Delete a project user from workspace projects users​

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

Delete a project user for a given workspace.

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

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
project_user_idintegertrueNumeric ID of the project user

Response​

200​

Successful operation.

400​

Possible error messages:

* Workspace not found
* Project user not found/accessible
* Invalid project_id

403​

User does not have access to this resource.

500​

Internal Server Error

GET WorkspaceProjects​

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

Get projects for given workspace.

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

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace

Query​

nametyperequireddescription
activebooleanfalseactive
sinceintegerfalseRetrieve projects created/modified/deleted since this date using UNIX timestamp.
billablebooleanfalsebillable
user_idsarrayfalseuser_ids
client_idsarrayfalseclient_ids
group_idsarrayfalsegroup_ids
statusesarrayfalsestatuses
namestringtruename
pageintegertruepage
sort_fieldstringtruesort_field
sort_orderstringtruesort_order
only_templatesbooleantrueonly_templates
per_pageintegerfalseNumber of items per page, default 151. Cannot exceed 200.

Response​

200​

Array of:

nametypedescription
activebooleanWhether the project is active or archived
actual_hoursinteger | nullActual hours
actual_secondsinteger | nullActual seconds
atstringLast updated date
auto_estimatesboolean | nullWhether estimates are based on task hours, premium feature
billableboolean | nullWhether the project is billable, premium feature
cidintegerClient ID legacy field
client_idinteger | nullClient ID
colorstringColor
created_atstringCreation date
currencystring | nullCurrency, premium feature
current_period
nametypedescription
end_datestring-
start_datestring-
Current project period, premium feature
end_datestringEnd date
estimated_hoursinteger | nullEstimated hours
estimated_secondsinteger | nullEstimated seconds
fixed_feenumberFixed fee, premium feature
idintegerProject ID
is_privatebooleanWhether the project is private
namestringName
permissionsstring-
ratenumberHourly rate
rate_last_updatedstring | nullLast date for rate change
recurringbooleanWhether the project is recurring, premium feature
recurring_parametersArray of
nametypedescription
custom_periodintegerCustom period, used when "period" field is "custom"
estimated_secondsintegerEstimated seconds
parameter_end_datestring | nullRecurring end date
parameter_start_datestringRecurring start date
periodstringPeriod
project_start_datestringProject start date
Project recurring parameters, premium feature
server_deleted_atstring | nullDeletion date
start_datestringStart date
statusstringStatus of the project (upcoming, active, ended, archived, deleted)
templateboolean | nullWhether the project is used as template, premium feature
template_idinteger | nullTemplate ID
widintegerWorkspace ID legacy field
workspace_idintegerWorkspace ID

403​

User does not have access to this resource.

500​

Internal Server Error

POST WorkspaceProjects​

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

Create project for given workspace.

curl -X POST https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/projects \
-H "Content-Type: application/json" \
-d '{"active":"boolean","auto_estimates":"boolean","billable":"boolean","cid":"integer","client_id":"integer","client_name":"string","color":"string","currency":"string","end_date":"string","estimated_hours":"integer","fixed_fee":"number","is_private":"boolean","name":"string","rate":"number","rate_change_mode":"string","recurring":"boolean","recurring_parameters":{"custom_period":"integer","period":"string","project_start_date":"string"},"start_date":"string","template":"boolean","template_id":"integer"}' \
-u <email>:<password>

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace

Body​

nametypedescription
activebooleanWhether the project is active or archived
auto_estimatesbooleanWhether estimates are based on task hours, optional, premium feature
billablebooleanWhether the project is set as billable, optional, premium feature
cidintegerClient ID, legacy
client_idintegerClient ID, optional
client_namestringClient name, optional
colorstringProject color
currencystringProject currency, optional, premium feature
end_datestringEnd date of a project timeframe
estimated_hoursintegerEstimated hours, optional, premium feature
fixed_feenumberProject fixed fee, optional, premium feature
is_privatebooleanWhether the project is private or not
namestringProject name
ratenumberHourly rate, optional, premium feature
rate_change_modestringRate change mode, optional, premium feature. Can be "start-today", "override-current", "override-all"
recurringbooleanProject is recurring, optional, premium feature
recurring_parameters
nametypedescription
custom_periodintegerRecurring custom period, the "period" field must be "custom"
periodstringRecurring period, example "monthly"
project_start_datestringRecurring start date
Project recurring parameters, optional, premium feature
start_datestringStart date of a project timeframe
templatebooleanProject is template, optional, premium feature
template_idintegerTemplate ID, optional

Response​

200​

nametypedescription
activebooleanWhether the project is active or archived
actual_hoursinteger | nullActual hours
actual_secondsinteger | nullActual seconds
atstringLast updated date
auto_estimatesboolean | nullWhether estimates are based on task hours, premium feature
billableboolean | nullWhether the project is billable, premium feature
cidintegerClient ID legacy field
client_idinteger | nullClient ID
colorstringColor
created_atstringCreation date
currencystring | nullCurrency, premium feature
current_period
nametypedescription
end_datestring-
start_datestring-
Current project period, premium feature
end_datestringEnd date
estimated_hoursinteger | nullEstimated hours
estimated_secondsinteger | nullEstimated seconds
fixed_feenumberFixed fee, premium feature
idintegerProject ID
is_privatebooleanWhether the project is private
namestringName
permissionsstring-
ratenumberHourly rate
rate_last_updatedstring | nullLast date for rate change
recurringbooleanWhether the project is recurring, premium feature
recurring_parametersArray of
nametypedescription
custom_periodintegerCustom period, used when "period" field is "custom"
estimated_secondsintegerEstimated seconds
parameter_end_datestring | nullRecurring end date
parameter_start_datestringRecurring start date
periodstringPeriod
project_start_datestringProject start date
Project recurring parameters, premium feature
server_deleted_atstring | nullDeletion date
start_datestringStart date
statusstringStatus of the project (upcoming, active, ended, archived, deleted)
templateboolean | nullWhether the project is used as template, premium feature
template_idinteger | nullTemplate ID
widintegerWorkspace ID legacy field
workspace_idintegerWorkspace ID

403​

User does not have access to this resource.

500​

Internal Server Error

PATCH WorkspaceProjects​

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

Bulk editing workspace projects.

curl -X PATCH https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/projects/{project_ids} \
-H "Content-Type: application/json" \
-d '{"array":[{"op":{"description":"Patch operation to perform, one of "add", "remove", "replace"","type":"string"},"path":{"description":"Path to the field to patch, example: "/color"","type":"string"},"value":{"object":{},"description":"Value to set when operation is "add" or "replace", example: "#000000". The value type actually depends on the field being patched."}}]}' \
-u <email>:<password>

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
project_idsstringtrueNumeric IDs of project ids, separated by comma. E.g.: 204301830,202700150,202687559

Body​

nametypedescription
arrayArray of
nametypedescription
opstringPatch operation to perform, one of "add", "remove", "replace"
pathstringPath to the field to patch, example: "/color"
valueValue to set when operation is "add" or "replace", example: "#000000". The value type actually depends on the field being patched.
Array of batch operations

Response​

200​

nametypedescription
failureArray of
nametypedescription
idinteger-
messagestring-
-
successArray of integer-

500​

Internal Server Error

GET WorkspaceProject​

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

Get project for given workspace.

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

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
project_idintegertrueNumeric ID of the project

Response​

200​

nametypedescription
activebooleanWhether the project is active or archived
actual_hoursinteger | nullActual hours
actual_secondsinteger | nullActual seconds
atstringLast updated date
auto_estimatesboolean | nullWhether estimates are based on task hours, premium feature
billableboolean | nullWhether the project is billable, premium feature
cidintegerClient ID legacy field
client_idinteger | nullClient ID
colorstringColor
created_atstringCreation date
currencystring | nullCurrency, premium feature
current_period
nametypedescription
end_datestring-
start_datestring-
Current project period, premium feature
end_datestringEnd date
estimated_hoursinteger | nullEstimated hours
estimated_secondsinteger | nullEstimated seconds
fixed_feenumberFixed fee, premium feature
idintegerProject ID
is_privatebooleanWhether the project is private
namestringName
permissionsstring-
ratenumberHourly rate
rate_last_updatedstring | nullLast date for rate change
recurringbooleanWhether the project is recurring, premium feature
recurring_parametersArray of
nametypedescription
custom_periodintegerCustom period, used when "period" field is "custom"
estimated_secondsintegerEstimated seconds
parameter_end_datestring | nullRecurring end date
parameter_start_datestringRecurring start date
periodstringPeriod
project_start_datestringProject start date
Project recurring parameters, premium feature
server_deleted_atstring | nullDeletion date
start_datestringStart date
statusstringStatus of the project (upcoming, active, ended, archived, deleted)
templateboolean | nullWhether the project is used as template, premium feature
template_idinteger | nullTemplate ID
widintegerWorkspace ID legacy field
workspace_idintegerWorkspace ID

403​

User does not have access to this resource.

500​

Internal Server Error

PUT WorkspaceProject​

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

Update project for given workspace.

curl -X PUT https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/projects/{project_id} \
-H "Content-Type: application/json" \
-d '{"active":"boolean","auto_estimates":"boolean","billable":"boolean","cid":"integer","client_id":"integer","client_name":"string","color":"string","currency":"string","end_date":"string","estimated_hours":"integer","fixed_fee":"number","is_private":"boolean","name":"string","rate":"number","rate_change_mode":"string","recurring":"boolean","recurring_parameters":{"custom_period":"integer","period":"string","project_start_date":"string"},"start_date":"string","template":"boolean","template_id":"integer"}' \
-u <email>:<password>

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
project_idintegertrueNumeric ID of the project

Body​

nametypedescription
activebooleanWhether the project is active or archived
auto_estimatesbooleanWhether estimates are based on task hours, optional, premium feature
billablebooleanWhether the project is set as billable, optional, premium feature
cidintegerClient ID, legacy
client_idintegerClient ID, optional
client_namestringClient name, optional
colorstringProject color
currencystringProject currency, optional, premium feature
end_datestringEnd date of a project timeframe
estimated_hoursintegerEstimated hours, optional, premium feature
fixed_feenumberProject fixed fee, optional, premium feature
is_privatebooleanWhether the project is private or not
namestringProject name
ratenumberHourly rate, optional, premium feature
rate_change_modestringRate change mode, optional, premium feature. Can be "start-today", "override-current", "override-all"
recurringbooleanProject is recurring, optional, premium feature
recurring_parameters
nametypedescription
custom_periodintegerRecurring custom period, the "period" field must be "custom"
periodstringRecurring period, example "monthly"
project_start_datestringRecurring start date
Project recurring parameters, optional, premium feature
start_datestringStart date of a project timeframe
templatebooleanProject is template, optional, premium feature
template_idintegerTemplate ID, optional

Response​

200​

nametypedescription
activebooleanWhether the project is active or archived
actual_hoursinteger | nullActual hours
actual_secondsinteger | nullActual seconds
atstringLast updated date
auto_estimatesboolean | nullWhether estimates are based on task hours, premium feature
billableboolean | nullWhether the project is billable, premium feature
cidintegerClient ID legacy field
client_idinteger | nullClient ID
colorstringColor
created_atstringCreation date
currencystring | nullCurrency, premium feature
current_period
nametypedescription
end_datestring-
start_datestring-
Current project period, premium feature
end_datestringEnd date
estimated_hoursinteger | nullEstimated hours
estimated_secondsinteger | nullEstimated seconds
fixed_feenumberFixed fee, premium feature
idintegerProject ID
is_privatebooleanWhether the project is private
namestringName
permissionsstring-
ratenumberHourly rate
rate_last_updatedstring | nullLast date for rate change
recurringbooleanWhether the project is recurring, premium feature
recurring_parametersArray of
nametypedescription
custom_periodintegerCustom period, used when "period" field is "custom"
estimated_secondsintegerEstimated seconds
parameter_end_datestring | nullRecurring end date
parameter_start_datestringRecurring start date
periodstringPeriod
project_start_datestringProject start date
Project recurring parameters, premium feature
server_deleted_atstring | nullDeletion date
start_datestringStart date
statusstringStatus of the project (upcoming, active, ended, archived, deleted)
templateboolean | nullWhether the project is used as template, premium feature
template_idinteger | nullTemplate ID
widintegerWorkspace ID legacy field
workspace_idintegerWorkspace ID

400​

Possible errors:

* Client with the ID {client ID} isn't present in workspace {workspace ID}
* Error in validating color '{color}'. Project color must be a hex value in the form of #\[0-9a-f\]{6}.

403​

Possible errors:

* Only admins may create projects in this workspace
* User does not have access to this resource.

500​

Internal Server Error

DELETE WorkspaceProject​

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

Delete project for given workspace.

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

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
project_idintegertrueNumeric ID of the project

Query​

nametyperequireddescription
teDeletionModestringfalseTime entries deletion mode: 'delete' or 'unassign'

Response​

200​

Successful operation.

403​

User does not have access to this resource.

500​

Internal Server Error
© 2024 Toggl. All rights reserved.