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

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
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
first_time_entrystringFirst time entry for this project. Only included if it was requested with with_first_time_entry
fixed_feenumberFixed fee, premium feature
idintegerProject ID
is_privatebooleanWhether the project is private
namestringName
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
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
first_time_entrystringFirst time entry for this project. Only included if it was requested with with_first_time_entry
fixed_feenumberFixed fee, premium feature
idintegerProject ID
is_privatebooleanWhether the project is private
namestringName
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
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: "/name"","type":"string"},"value":{"object":{},"description":"Value to set when operation is "add" or "replace", example: "New name". 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: "/name"
valueValue to set when operation is "add" or "replace", example: "New name". 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

Query

nametyperequireddescription
with_first_time_entrybooleanfalseWill include the first time entry date 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
first_time_entrystringFirst time entry for this project. Only included if it was requested with with_first_time_entry
fixed_feenumberFixed fee, premium feature
idintegerProject ID
is_privatebooleanWhether the project is private
namestringName
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
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
first_time_entrystringFirst time entry for this project. Only included if it was requested with with_first_time_entry
fixed_feenumberFixed fee, premium feature
idintegerProject ID
is_privatebooleanWhether the project is private
namestringName
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
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

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
© 2023 Toggl. All rights reserved.