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

NameTypeDescription
itemsArray of object-
items
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
integration_ext_idstringThe external ID of the linked entity in the external system (e.g. JIRA/SalesForce)
integration_ext_typestringThe external type of the linked entity in the external system (e.g. JIRA/SalesForce)
integration_providerstringThe provider (e.g. JIRA/SalesForce) that has an entity linked to this Toggl Track entity
namestringName of the client
notesstring-
permissionsstringList of authorization permissions for this client.
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","notes":"string","wid":"integer"\}' \
-u <email>:<password>

Parameters

Path

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace

Body

NameTypeDescription
namestringClient name
notesstring-
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
integration_ext_idstringThe external ID of the linked entity in the external system (e.g. JIRA/SalesForce)
integration_ext_typestringThe external type of the linked entity in the external system (e.g. JIRA/SalesForce)
integration_providerstringThe provider (e.g. JIRA/SalesForce) that has an entity linked to this Toggl Track entity
namestringName of the client
notesstring-
permissionsstringList of authorization permissions for this client.
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
integration_ext_idstringThe external ID of the linked entity in the external system (e.g. JIRA/SalesForce)
integration_ext_typestringThe external type of the linked entity in the external system (e.g. JIRA/SalesForce)
integration_providerstringThe provider (e.g. JIRA/SalesForce) that has an entity linked to this Toggl Track entity
namestringName of the client
notesstring-
permissionsstringList of authorization permissions for this client.
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","notes":"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
notesstring-
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
integration_ext_idstringThe external ID of the linked entity in the external system (e.g. JIRA/SalesForce)
integration_ext_typestringThe external type of the linked entity in the external system (e.g. JIRA/SalesForce)
integration_providerstringThe provider (e.g. JIRA/SalesForce) that has an entity linked to this Toggl Track entity
namestringName of the client
notesstring-
permissionsstringList of authorization permissions for this client.
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

NameTypeDescription
itemsArray of integer-

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":[\{\}],"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
integration_ext_idstringThe external ID of the linked entity in the external system (e.g. JIRA/SalesForce)
integration_ext_typestringThe external type of the linked entity in the external system (e.g. JIRA/SalesForce)
integration_providerstringThe provider (e.g. JIRA/SalesForce) that has an entity linked to this Toggl Track entity
namestringName of the client
notesstring-
permissionsstringList of authorization permissions for this client.
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.