HubstaffDeveloper Portal

Timesheets

Weekly timesheet summaries for approval workflows

Endpoints
Recent changes (1)
  1. New endpoint

    Update timesheet status

    New endpoint to change a timesheet's status: open, submitted, approved, or denied.

    A denial_reason is required when denying. Approving a period with pending manual time requests or time off requests returns 422 (error_code 14905 / 14906); repeat the request with confirm_pending_manual_time_request_denial or acknowledge_pending_time_off_requests set to true.

List organization timesheets

GET/v2/organizations/{organization_id}/timesheets

Returns a collection of timesheets (aggregate approval records) for the given organization.

Results can be filtered by date[start]/[stop], approved[start], and status.

Note: Timesheets are aggregate records used by the timesheet approval system, not individual time entries.

Parameters

NameInTypeDescription
organization_idrequired
pathinteger (int32)
page_start_id
queryinteger (int32)
The page start ID.
page_limit
queryinteger (int32)
The default page size
date[start]
querystring (date)
Start date (ISO 8601)
date[stop]
querystring (date)
Stop date (ISO 8601, Inclusive)
approved[start]
querystring (date)
Includes timesheets approved since the specified start date, considering UTC timezone (ISO 8601)
status
querystring
Invoice status
Possible valuesopensubmittedapproveddenied
include
queryarray string[]
Specify related data to side load.
Possible valuesusers

Responses

200A list of timesheets
object
  • timesheetsarray
    array<object>
    items
    object

    Timesheet model

    • idinteger required

      Timesheet ID

    • paidboolean required

      Is the timesheet paid?

    • user_idinteger required

      User ID

    • organization_idinteger required

      Organization ID

    • team_payment_idinteger

      Team payment ID

    • team_invoice_idinteger

      Team invoice ID

    • statusstring required

      Status

    • keyboardinteger required

      Percentage of time keyboard was active within the time worked

    • mouseinteger required

      Percentage of time mouse was active within the time worked

    • overallinteger required

      Percentage of overall time active within the time worked

    • trackedinteger required

      Total time worked in seconds

    • input_trackedinteger required

      Total time worked in seconds when inputs (keyboard, mouse) were active

    • start_datestring required

      Start date

    • stop_datestring required

      Stop date

    • approved_onstring

      Approving date

    • submitted_onstring

      Submission date

    • approved_by_idinteger

      Approving User ID

    • denial_reasonstring

      Denial reason

    • lockedboolean required

      Is the timesheet locked

    • created_atstring required

      When the record was created

    • updated_atstring required

      When the record was last updated

Example response
json
{
  "timesheets": [
    {
      "id": 0,
      "paid": false,
      "user_id": 0,
      "organization_id": 0,
      "team_payment_id": 0,
      "team_invoice_id": 0,
      "status": "string",
      "keyboard": 0,
      "mouse": 0,
      "overall": 0,
      "tracked": 0,
      "input_tracked": 0,
      "start_date": "2024-01-15",
      "stop_date": "2024-01-15",
      "approved_on": "2024-01-15",
      "submitted_on": "2024-01-15",
      "approved_by_id": 0,
      "denial_reason": "string",
      "locked": false,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_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"
  ]
}

Update timesheet status

PUT/v2/timesheets/{timesheet_id}

Updates a timesheet status or updates the denial reason on an already denied timesheet.

Allowed statuses are open, submitted, approved, and denied. A denial_reason is required when transitioning a timesheet to denied.

Approving a timesheet can require explicit confirmation when the period has pending manual time requests or pending time off requests. If pending manual time requests would be denied, the endpoint returns 422 with error_code 14905; repeat the request with confirm_pending_manual_time_request_denial set to true. If the period has pending time off requests, the endpoint returns 422 with error_code 14906; repeat the request with acknowledge_pending_time_off_requests set to true.

Parameters

NameInTypeDescription
timesheet_idrequired
pathinteger (int32)
Timesheet ID

Request body

object

Update timesheet status

  • statusstring required

    New status

  • denial_reasonstring

    Denial reason

  • confirm_pending_manual_time_request_denialboolean

    Required to approve a timesheet with pending manual time requests that will be denied.

  • acknowledge_pending_time_off_requestsboolean

    Required to approve a timesheet with pending time off requests in the same period.

Responses

200The updated timesheet
object
  • timesheetobject
    object

    Timesheet model

    • idinteger required

      Timesheet ID

    • paidboolean required

      Is the timesheet paid?

    • user_idinteger required

      User ID

    • organization_idinteger required

      Organization ID

    • team_payment_idinteger

      Team payment ID

    • team_invoice_idinteger

      Team invoice ID

    • statusstring required

      Status

    • keyboardinteger required

      Percentage of time keyboard was active within the time worked

    • mouseinteger required

      Percentage of time mouse was active within the time worked

    • overallinteger required

      Percentage of overall time active within the time worked

    • trackedinteger required

      Total time worked in seconds

    • input_trackedinteger required

      Total time worked in seconds when inputs (keyboard, mouse) were active

    • start_datestring required

      Start date

    • stop_datestring required

      Stop date

    • approved_onstring

      Approving date

    • submitted_onstring

      Submission date

    • approved_by_idinteger

      Approving User ID

    • denial_reasonstring

      Denial reason

    • lockedboolean required

      Is the timesheet locked

    • created_atstring required

      When the record was created

    • updated_atstring required

      When the record was last updated

Example response
json
{
  "timesheet": {
    "id": 0,
    "paid": false,
    "user_id": 0,
    "organization_id": 0,
    "team_payment_id": 0,
    "team_invoice_id": 0,
    "status": "string",
    "keyboard": 0,
    "mouse": 0,
    "overall": 0,
    "tracked": 0,
    "input_tracked": 0,
    "start_date": "2024-01-15",
    "stop_date": "2024-01-15",
    "approved_on": "2024-01-15",
    "submitted_on": "2024-01-15",
    "approved_by_id": 0,
    "denial_reason": "string",
    "locked": false,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_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"
  ]
}