Tool Classifications

Manage productivity and category classifications for applications and URL sites

Endpoints

GET/v2/organizations/{organization_id}/insights/tool_categories
GET/v2/organizations/{organization_id}/insights/tool_classifications
PATCH/v2/organizations/{organization_id}/insights/tool_classifications

List tool categories

GET/v2/organizations/{organization_id}/insights/tool_categories

Returns the list of available category names for tool classifications.

Categories are global and shared across all organizations. Use the returned names in the category field when updating tool classifications via PATCH /organizations/:id/insights/tool_classifications.

Requires Owner or Organization Manager role. Requires the Insights add-on.

Parameters

Name	In	Type	Description
organization_idrequired	path	integer (int32)

Responses

200List tool categories

List tool classifications

GET/v2/organizations/{organization_id}/insights/tool_classifications

Returns a paginated list of Applications or URL sites (one tool_type per request) with their productivity and category classifications for the given organization.

tool_type is required. Results can be further filtered by name (search), productivity, and job_type. Use GET /organizations/:id/job_types to discover valid job_type values for this organization.

Pagination is id-based within the chosen tool_type: to get the next page, pass pagination.next_page_start_id from the previous response as page_start_id.

Requires Owner or Organization Manager role. Requires the Insights add-on.

Parameters

Name	In	Type	Description
organization_idrequired	path	integer (int32)
page_start_id	query	integer (int32)	The page start ID.
page_limit	query	integer (int32)	The default page size
tool_typerequired	query	string	Tool type to list: application or url Possible values`applicationurl`
name	query	string	Filter by tool name (case-insensitive substring match)
job_type	query	string	Filter by job type (case-insensitive, must match a valid occupation).
productivity	query	string	Filter by productivity classification Possible values`corenon_coreunproductive`

Responses

200A list of tool classifications

object

tool_classificationsarray
array<object>
items
object
ToolClassification model
- idinteger required
  Tool ID (Application or URL site ID)
- tool_typestring required
  Tool type: application or url
- namestring required
  Tool display name
- productivitystring required
  Effective productivity: core, non_core, or unproductive
- job_typestring required
  Job type for this classification. Null = all.
- categorystring required
  Category name. Defaults to the tool's empty category ('Uncategorized' for apps, 'Browsing' for URLs) when none set.

Example response

json

{
  "tool_classifications": [
    {
      "id": 0,
      "tool_type": "string",
      "name": "string",
      "productivity": "string",
      "job_type": "string",
      "category": "string"
    }
  ]
}

400Invalid parameters

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

401Unauthorized

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

403API access is only for organizations on an active plan

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

404Could not find record

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

429Rate limit exceeded

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

Update tool classifications

PATCH/v2/organizations/{organization_id}/insights/tool_classifications

Batch updates productivity classifications and categories for up to 100 tools.

Each item must include id and tool_type. Provide productivity and/or category to update. Use job_type to scope a productivity change to a specific role (see GET /organizations/:id/job_types). category and job_type are mutually exclusive within an item: category applies globally, so it can only be set when job_type is omitted. Changes are applied atomically — if any item fails validation, no changes are saved. On success, returns 204 No Content.

Note: productivity changes only affect future tool usage data, not historical records.

Requires Owner or Organization Manager role. Requires the Insights add-on.

Parameters

Name	In	Type	Description
organization_idrequired	path	integer (int32)

Request body

object

Update tool classifications

tool_classificationsarray required
array<object>
items
object
- idinteger required
  Tool ID
- tool_typestring required
  Tool type
- productivitystring
  Productivity classification to set
- job_typestring
  Job type for productivity (case-insensitive). Omit to apply globally.
- categorystring
  Category name (case-insensitive). Null resets to default. See GET /organizations/:id/insights/tool_categories for valid values.

Responses

200204 No Content on success

object

tool_classificationobject
object
ToolClassification model
- idinteger required
  Tool ID (Application or URL site ID)
- tool_typestring required
  Tool type: application or url
- namestring required
  Tool display name
- productivitystring required
  Effective productivity: core, non_core, or unproductive
- job_typestring required
  Job type for this classification. Null = all.
- categorystring required
  Category name. Defaults to the tool's empty category ('Uncategorized' for apps, 'Browsing' for URLs) when none set.

Example response

json

{
  "tool_classification": {
    "id": 0,
    "tool_type": "string",
    "name": "string",
    "productivity": "string",
    "job_type": "string",
    "category": "string"
  }
}

400Invalid parameters

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

401Unauthorized

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

403API access is only for organizations on an active plan

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

404Could not find record

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

429Rate limit exceeded

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}