Skip to main content

Clients

GET List clients​

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

List clients from workspace.

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

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace

Query​

nametyperequireddescription
statusstringfalseUse 'active' to only list active clients, 'archived' to only list archived clients and 'both' to retrieve active and archived clients. If not provided, only active clients are returned.
namestringfalseIf provided, allows to filter by client name in a case insensitive manner, returning all the ones that contain the given string.

Response​

200​

Array of:

nametypedescription
archivedbooleanIsArchived is true if the client is archived
atstringWhen was the last update
creator_idintegerCreatorID is the ID of the user who created the client
idintegerClient ID
namestringName of the client
permissionsstringList of authorization permissions for this client.
server_deleted_atstringWhen was deleted, null if not deleted
widintegerWorkspace ID

400​

Client status is invalid

403​

Forbidden

500​

Internal Server Error

POST Create client​

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

Create workspace client.

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

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace

Body​

nametypedescription
namestringClient name
widintegerWorkspace ID

Response​

200​

nametypedescription
archivedbooleanIsArchived is true if the client is archived
atstringWhen was the last update
creator_idintegerCreatorID is the ID of the user who created the client
idintegerClient ID
namestringName of the client
permissionsstringList of authorization permissions for this client.
server_deleted_atstringWhen was deleted, null if not deleted
widintegerWorkspace ID

400​

Possible error messages:

* Client name maximum length is {max_client_length}
* Client name cannot be empty

403​

Forbidden

500​

Internal Server Error

GET Load client from ID​

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

Load client from workspace.

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

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
client_idintegertrueNumeric ID of the client

Response​

200​

nametypedescription
archivedbooleanIsArchived is true if the client is archived
atstringWhen was the last update
creator_idintegerCreatorID is the ID of the user who created the client
idintegerClient ID
namestringName of the client
permissionsstringList of authorization permissions for this client.
server_deleted_atstringWhen was deleted, null if not deleted
widintegerWorkspace ID

403​

Forbidden

404​

No client with ID {client_id} was found

500​

Internal Server Error

PUT Change client​

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

Update workspace client.

Note: use /workspaces/{workspace_id}/clients/{client_id}/archive to archive the client and /workspaces/{workspace_id}/clients/{client_id}/restore to restore it.

curl -X PUT https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/clients/{client_id} \
-H "Content-Type: application/json" \
-d '{"name":"string","wid":"integer"}' \
-u <email>:<password>

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
client_idintegertrueNumeric ID of the client

Body​

nametypedescription
namestringClient name
widintegerWorkspace ID

Response​

200​

nametypedescription
archivedbooleanIsArchived is true if the client is archived
atstringWhen was the last update
creator_idintegerCreatorID is the ID of the user who created the client
idintegerClient ID
namestringName of the client
permissionsstringList of authorization permissions for this client.
server_deleted_atstringWhen was deleted, null if not deleted
widintegerWorkspace ID

400​

Possible error messages:

* Client name maximum length is {max_client_length}
* Client name cannot be empty

403​

Forbidden

404​

Client doesn't exist in the workspace.

500​

Internal Server Error

DELETE Delete client​

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

Delete workspace client.

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

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
client_idintegertrueNumeric ID of the client

Response​

200​

Successful operation.

403​

Forbidden

404​

No client with ID {client_id} was found

500​

Internal Server Error

POST Archives client​

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

Archives a workspace client and related projects. Only for premium workspaces.

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

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
client_idintegertrueNumeric ID of the client

Response​

200​

Projects that were archived with the client

Array of:

403​

Forbidden

404​

No client with ID {client_id} was found

500​

Internal Server Error

POST Restores client and related projects.​

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

Restores client and all related or specified projects from the given workspace.

curl -X POST https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/clients/{client_id}/restore \
-H "Content-Type: application/json" \
-d '{"projects":["integer"],"restore_all_projects":"boolean"}' \
-u <email>:<password>

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
client_idintegertrueNumeric ID of the client

Body​

nametypedescription
projectsArray of integer-
restore_all_projectsboolean-

Response​

200​

Returns the restored client
nametypedescription
archivedbooleanIsArchived is true if the client is archived
atstringWhen was the last update
creator_idintegerCreatorID is the ID of the user who created the client
idintegerClient ID
namestringName of the client
permissionsstringList of authorization permissions for this client.
server_deleted_atstringWhen was deleted, null if not deleted
widintegerWorkspace ID

400​

Bad Request

403​

Forbidden

404​

No client with ID {client_id} was found

500​

Internal Server Error
© 2024 Toggl. All rights reserved.