HubstaffDeveloper Portal

Smart notifications

View triggered smart notifications

Endpoints

List smart notifications

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

Returns the smart notification ocurrences for the given organization. By default, the API returns only the occurrences for which the API caller (current user) is a recipient of the notification.

Start and stop dates are required, the remaining parameters are optional.

When using the user_ids or team_ids filter, the API will filter the results based on the users who triggered the notification, not the users who will receive the notification.

Parameters

NameInTypeDescription
organization_idrequired
pathinteger (int32)
page_start_id
queryinteger (int32)
The page start ID.
page_limit
queryinteger (int32)
The default page size
user_ids
queryarray integer[]
List of user IDs
team_ids
queryarray integer[]
List of team IDs
created[start]required
querystring (date-time)
Start time (ISO 8601)
created[stop]required
querystring (date-time)
Stop time (ISO 8601, exclusive)
rule_id
queryinteger (int32)
ID of the smart notification rule to filter by
include
queryarray string[]
Specify related data to side load.
Possible valuesusers

Responses

200A list of smart notifications ocurrences
object
  • smart_notificationsarray
    array<object>
    items
    object

    SmartNotification model

    • idinteger required

      Smart notification ID

    • matchesarray required

      Matches that triggered the notification, i.e. users who violated the rule

      array<object>

      Matches that triggered the notification, i.e. users who violated the rule

      items
      object
      • user_idinteger required

        User ID

      • valuenumber required

        Value of the metric that the user got for the rule specified metric

    • total_countinteger required

      Total number of matches/users who triggered the notification

    • rule_snapshotobject required

      Snapshot of rule that triggered the notification at the time it was created

      object
      • idinteger required

        Smart notification rule ID

      • namestring required

        Smart notification rule name

      • frequencystring required

        Determines how often the conditions for notifications are checked

      • metric_typestring required

        Metric type being monitored

      • conditionstring required

        Comparison condition that triggered the notification

      • condition_valuenumber required

        Rule threshold value (in seconds if metric type is work_time or time_spent_in_tool

      • time_unitstring

        Duration of time over which the rule was evaluated

    • froms required

      Rule evaluated over a range starting on this date

    • tos required

      Rule evaluated over a range ending on this date

    • created_atstring required

      When the record was created

Example response
json
{
  "smart_notifications": [
    {
      "id": 0,
      "matches": [
        {
          "user_id": 0,
          "value": 0
        }
      ],
      "total_count": 0,
      "rule_snapshot": {
        "id": 0,
        "name": "string",
        "frequency": "string",
        "metric_type": "string",
        "condition": "string",
        "condition_value": 0,
        "time_unit": "string"
      },
      "from": null,
      "to": null,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}
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"
  ]
}