Hubstaff - Setup Guide

Overview

The Hubstaff source syncs Hubstaff organization, member, activity, daily activity, and time off request data into Daspire.

Prerequisites

• A Hubstaff account that can authorize API access for each organization you want to sync.

Authentication

1. In Daspire, click Authenticate with Hubstaff.
2. Sign in to Hubstaff and approve the requested OAuth access.
3. After authorization succeeds, choose one or more organizations from the list Daspire loads from Hubstaff.
4. Daspire stores the OAuth tokens securely. You do not need to enter a Hubstaff OAuth client secret or refresh token manually.

The connector uses Hubstaff OAuth 2.0 / OIDC authorization code flow and the Hubstaff token endpoint:

https://account.hubstaff.com/access_tokens

If Hubstaff rotates the refresh token during a sync, the connector immediately switches to the rotated token for subsequent Hubstaff API requests.

Organizations

Daspire normally fills this field from the organizations returned by Hubstaff after OAuth. Select the organization or organizations you want this source to sync.

Manual entry is only a fallback for existing or migrated configurations. To find a Hubstaff Organization ID manually:

1. Log in to Hubstaff.
2. Open the organization dashboard.
3. Copy the numeric organization ID from the URL, for example:

https://app.hubstaff.com/dashboard/12345/team

For one organization, use 12345. For multiple organizations, use a comma-separated list such as 12345,67890.

Configuration

Field	Required	Notes
Hubstaff Organizations	Yes	Select one or more Hubstaff organizations after OAuth. Existing/manual configs can use one ID or a comma-separated list.
Start Date	Yes	UTC date or date-time used by activities and daily_activities incremental reads.
Recent Activity Refresh Window (Days)	No	Number of recent days to re-read on each ongoing incremental sync. Defaults to 3 days.
End Date	No	Optional bounded end date for backfills. Leave empty to sync through now.
Page Limit	No	Advanced setting for Hubstaff list pagination.

Activity Refresh Window

Hubstaff can update or backfill time and activity records after their original activity date. To capture those late changes, Daspire re-reads the most recent activity window on ongoing incremental syncs.

• On the first sync, activities and daily_activities start from Start Date.
• On later incremental syncs without End Date, the connector starts from the saved cursor minus Recent Activity Refresh Window (Days), capped at Start Date, and syncs through now.
• When End Date is set, the connector keeps the sync bounded to the fixed historical range instead of rolling forward to now.

The activity streams intentionally emit records from the refresh window again. Use a destination sync mode that can update existing records by primary key when you need corrected Hubstaff values to replace older copies.

Supported Streams

Stream	Sync Modes	Primary Key	Cursor
organizations	Full refresh	id	None
members	Full refresh	organization_id, user_id	None
activities	Full refresh, incremental	organization_id, id	time_slot
daily_activities	Full refresh, incremental	organization_id, id	date
time_off_requests	Full refresh	organization_id, id	None

The activity streams request Hubstaff side-loaded users, projects, and tasks where supported by the API and include those arrays on emitted records.

Limits

• activities is sliced into Hubstaff time_slot[start] / time_slot[stop] requests no longer than 7 days.
• daily_activities is sliced into Hubstaff date[start] / date[stop] requests no longer than 31 days.
• Hubstaff rate limits may return HTTP 429. Daspire retries these requests with bounded backoff.
• Hubstaff 5xx and network timeouts are retried with bounded backoff.

Troubleshooting

Error	Action
Authentication failed or HTTP 401	Re-authenticate the Hubstaff source in Daspire.
HTTP 403 or missing organization access	Re-authorize with a Hubstaff user that can access the selected organization.
Organization ID not found	Re-authorize and select the organization again. For manual configs, re-check the ID from the Hubstaff dashboard URL.
Rate limit exceeded	Wait for the Hubstaff rate limit window to reset, then retry.
Empty activity results	Confirm the Start Date / End Date range and that Hubstaff has activity data in that period.

Additional Resources

• Hubstaff API Documentation
• Hubstaff Authentication Guide