Add-ons

ROOK offers various add-ons to enhance the integration experience. Some add-ons are activated by default, while others must be requested. Clients requiring additional capabilities should contact their account manager.

Add-On	Additional Feature	Activated by Default
Time Zone	Ensures local time delivery	Yes
Data Cleaning	Improves data accuracy	Yes
Deactivate Granular Data	Optimizes data delivery	No
Notification Webhook	Real-time integration notifications	No
Callback URL Setup	Redirects users post-connection	No
Connections Page	Simplifies user authorization	Yes (for sandbox)
Pre-Existing Data	Historical data retrieval	Yes
Steps Events in API	Hourly step polling	No

Time Zone

The Time Zone add-on ensures that daily summary data is extracted and delivered based on each country’s local time zone.

This add-on is activated by default in ROOK Connect. Additional details are available in the Data Extraction section.

To set up the time zone of your users, check the following endpoint.

Data Cleaning

The Data Cleaning add-on prioritizes and cleans health data from multiple sources for the same user, ensuring the delivery of accurate and comprehensive data structures. This feature is activated by default in ROOK Connect. For more details, visit the Data Processing section.

Deactivate Granular Data

The Deactivate Granular Data add-on omits detailed health metrics, such as heart rate and blood pressure, to reduce payload sizes. This optimization benefits clients with limited capacity to process large JSON files. The add-on is available upon request; clients can contact their account manager for activation. Further details are provided in the Granular Data Exclusion section.

Notification Webhook

The Notification Webhook add-on provides real-time updates about integration-specific actions, including user creation, data source connections, and failed notifications. This webhook does not deliver health data but provides essential updates for monitoring and troubleshooting.

User Management Notifications

Notifications are triggered by actions such as:

New user creation
Data source connections or disconnections
Failed data extractions

Example Notification for User Connection

{
  "client_uuid": "123456789",
  "user_id": "UserTest12345",
  "data_source": "garmin",
  "action": "user_connected",
  "level": "info",
  "message": "A new user has been successfully linked",
  "action_datetime": "2024-06-03T19:10:43.419390",
  "environment": "production"
}

For setup guidance, refer to the Data Delivery section.

Callback URL Setup

The Callback URL Setup add-on enables clients to define a redirect URL for users after completing data source authorization. This feature enhances user flow by guiding users back to the client’s APP or another designated view.

Usage Example:

https://api.rook-connect.com/api/v1/client_uuid/123456789/user_id/UserTest12345/data_sources/authorizers?redirect_url=https://www.yourapp.com

For activation, contact the assigned account manager.

Connections Page

The Connections Page simplifies user authorization by presenting a pre-configured interface with buttons for supported data sources. This tool is ideal for sandbox testing and rapid development but is not recommended for production environments.

Key Features

Pre-Configured Interface: Provides a dynamic view of supported data sources using the /authorizers endpoint.
Configuration in ROOK Portal: Allows adjustments to displayed data sources and testing connectivity.

Production Considerations

For production environments, clients should create a custom authorization interface by directly using the /authorizer endpoint for each datasource. This endpoint returns:

Authorization status and URL — Returns the user’s authorization status and, if not authorized, an authorization URL to start the process.

More information is available in the API documentation.

Important: About the Pre-Configured Interface

The previous /data_sources/authorizers endpoint is deprecated and should not be used for Production flows.

Pre-Existing Data

The Pre-Existing Data feature retrieves prior health data from users upon their initial connection. This includes up to:

7 days of pre-existing data for API-based sources.
29 days of pre-existing data for mobile-based sources via SDKs.

Key Benefits

Immediate Insights: Pre-existing data enables instant analysis of user health metrics upon connection.
ROOK Score Calculation: A ROOK Score is calculated for each day of extracted pre-existing data, resulting in up to 7 scores for API-based sources and up to 29 scores for SDK-based sources. These scores are delivered within * *24 hours**, ensuring all prior data is processed accurately.
Seamless Integration: Pre-existing data is delivered through the Data Webhook, using the same JSON structure as summaries and events, ensuring compatibility with existing systems.

Important Notes

Source-Specific Variations:
- Polar: Does not provide physical or body summaries in pre-existing data.
- Whoop: Returns the same body summary for the past seven days, reflecting the most recent data available.
ROOK Score Calculation: Each extracted day of pre-existing data contributes to a separate ROOK Score, ensuring comprehensive scoring and insights.

For additional details, visit the News Page.

Steps Events in API

This Add-On enables the extraction of time-based step events using API-based data sources, offering granularity similar to that obtained through SDK-based data sources. It operates through a polling system that automatically queries third-party APIs such as Whoop, Oura, Garmin, Fitbit, Withings or Polar every hour, applying validation rules to ensure data consistency, ascending order, and deduplication.

note

To activate this functionality, please contact the ROOK support team or your account manager.

Functionality

Feature	Description
Hourly extraction	A polling system queries third-party APIs every hour to retrieve accumulated step counts.
Data consistency	Extraction logic mirrors SDK behavior, with harmonized structure and frequency.
Duplicity rules	Only ascending values are accepted. If multiple sources are connected, the highest value is selected. When step values are zero or null, they fall back to the last known valid value.
Data structure	The event is delivered in `steps_event` format, including `datetime`, `user_id`, data source, and accumulated steps.
Webhook delivery	Data is sent exclusively via the `Data Webhook`. Therefore, Cannot be fetched via API request, steps events are only delivered via the Data Webhook.
Notification Webhook (Optional)	If a fetch failure occurs (timeout, authentication error, quota limit), a notification is sent to the client's `Notification Webhook` (if it has one).

Steps Events Flow Diagram

Payload Structure

{
  "version": 2,
  "data_structure": "steps_event",
  "client_uuid": "",
  "user_id": "",
  "document_version": 1,
  "auto_detected": false,
  "physical_health": {
    "events": {
      "steps_event": [
        {
          "metadata": {
            "datetime_string": "2025-02-27T21:29:26.747000+05:00",
            "user_id_string": "10053949724",
            "sources_of_data_array": ["Garmin"],
            "was_the_user_under_physical_activity_bool": false
          },
          "steps": {
            "accumulated_steps_int": 8546
          },
          "non_structured_data_array": []
        }
      ]
    }
  }
}

Add-ons

Time Zone​

Data Cleaning​

Deactivate Granular Data​

Notification Webhook​

User Management Notifications​

Example Notification for User Connection​

Callback URL Setup​

Connections Page​

Key Features​

Production Considerations​

Pre-Existing Data​

Key Benefits​

Important Notes​

Steps Events in API​

Functionality​

Steps Events Flow Diagram​

Payload Structure​