Skip to main content

Add-ons

Summary

The ROOK Connect platform offers multiple add-ons to customize the data integration architecture. Core features like Time Zone alignment and Data Cleaning are enabled by default, while advanced capabilities such as Granular Data extraction, Notification Webhooks, and hourly Steps Events require manual activation. Furthermore, the Pre-Existing Data feature automatically retrieves up to seven days of historical records for API-based sources upon the initial user connection, facilitating immediate health metric analysis.

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-OnAdditional FeatureActivated by Default
Time ZoneEnsures local time deliveryYes
Data CleaningImproves data accuracyYes
Activate Granular DataOptimizes data deliveryNo
Notification WebhookReal-time integration notificationsNo
Callback URL SetupRedirects users post-connectionNo
Connections PageSimplifies user authorizationYes For sandbox
Pre-Existing DataHistorical data retrievalYes
Steps Events in APIHourly step pollingNo
Lab DataLaboratory document processingNo
EHR/EMR Clinical Ready BetaFHIR R4 clinical documentsNo
Medical Devices BetaDevice metadata enrichmentNo
Branded Auth On HoldA fully personalized experienceNo

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.

Activate Granular Data​

The Activate Granular Data add-on enables access to detailed health metrics such as heart rate, heart rate variability, blood pressure, and additional minute-level readings. This option increases payload depth and provides a richer dataset for clients who need more precise insights. The add-on is disabled by default. To enable it, clients must request activation through their account manager. More information is available in the Granular Data 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.
    • Garmin: If the same user attempts to link twice within the same client account but with a different user_id, preexisting data will only be sent during the first link. No preexisting data will be sent on the second link.

  • 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.

note

In the Sandbox environment, the Pre-Existing Data feature is enabled and active by default, allowing teams to test the full flow without additional configuration. In Production, this feature is disabled by default and must be manually activated before use. For activation and additional support, please contact the ROOK support team.

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 enable this functionality in production, please contact the ROOK support team or your account manager.

Functionality​

FeatureDescription
Hourly extractionA polling system queries third-party APIs every hour to retrieve accumulated step counts.
Data consistencyExtraction logic mirrors SDK behavior, with harmonized structure and frequency.
Duplicity rulesOnly 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 structureThe event is delivered in steps_event format, including datetime, user_id, data source, and accumulated steps.
Webhook deliveryData 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​

steps-events-in-api_flow.png

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": []
        }
      ]
    }
  }
}

Lab Data​

Lab Data enables you to integrate laboratory results into your application through a single API. Submit a laboratory document in PDF or image format and receive structured results once processing is complete.

ROOK processes each document asynchronously through an extraction, normalization, and validation pipeline. Once processing is complete, the results are automatically delivered to the Data Webhook configured for your integration.

Lab Data is designed to simplify the integration of clinical laboratory data into digital applications without requiring you to build your own document processing infrastructure.

What does Lab Data do?​

Lab Data automates the processing of laboratory documents, transforming unstructured information into consistent, structured data that is ready for your application.

During processing, ROOK:

  • Extracts biomarkers from the document.
  • Identifies the clinical panels included in the report.
  • Normalizes biomarker names, units, and values.
  • Maps biomarkers to LOINC codes when available.
  • Validates the consistency of each biomarker.
  • Generates a structured response in either ROOK JSON or FHIR R4 format.

The entire processing pipeline runs within ROOK's infrastructure. Your application only needs to submit the document and receive the processed results through a Data Webhook.

How it works​

Integrating Lab Data consists of four steps.

  1. Your application submits a laboratory document to the Lab Data endpoint.
  2. ROOK receives the document and places it into the processing queue.
  3. The document goes through the extraction, normalization, and validation pipeline.
  4. Once processing is complete, ROOK sends the structured results to your configured Data Webhook.

Lab Data processes documents asynchronously. The API response only confirms that the document has been successfully received. Processing results are delivered later through the configured Data Webhook.

Data Webhook required

Lab Data delivers processing results exclusively through a Data Webhook.

Before submitting your first laboratory document, make sure you have configured an HTTPS endpoint that is publicly accessible. ROOK sends an HTTP POST request to this endpoint each time a document is processed successfully.

If you have not configured a Data Webhook yet, see the Data Webhooks guide before continuing.

Use cases​

Lab Data is designed for applications that need to incorporate laboratory results without building their own document extraction and normalization system.

Common use cases include:

  • Digital health platforms.
  • Wellness applications.
  • Preventive care programs.
  • Remote patient monitoring solutions.
  • Clinical research platforms.
  • Systems that consolidate laboratory data from multiple providers.

Document requirements​

Before submitting a document, verify that it meets the following requirements.

Supported formats​

Lab Data accepts the following file formats:

  • PDF
  • JPEG
  • PNG

If you submit a JPEG or PNG image, ROOK automatically converts it to PDF before processing begins.

Maximum file size​

  • The maximum supported file size is 10 MB.
  • Requests that exceed this limit are rejected.

Sample collection date and time​

  • The document must include a visible sample collection date and time.
  • This information is required to process the document.
  • If either the date or time is missing or cannot be read, processing fails and no Data Webhook is sent.

Document quality​

For the best processing results, we recommend that documents:

  • Are complete.
  • Are not cropped.
  • Are clearly legible.
  • Have sufficient image resolution.
  • Do not contain shadows or reflections over the content.
  • Are correctly oriented.

Integrate Lab Data​

Once you have configured a Data Webhook and verified that your documents meet the processing requirements, you can begin submitting laboratory documents to Lab Data.

The integration exposes a single endpoint for document submission. Each request starts an asynchronous processing workflow and returns a unique identifier for the submitted document.

There is no endpoint to check the processing status. All processing results are delivered automatically through your configured Data Webhook.

Endpoint​

Submit laboratory documents using the following endpoint.

POST https://api.lab.rook-connect.<com | review>/client_uuid/{client_uuid}/user_id/{user_id}
Path parameters​
ParameterDescription
client_uuidThe client identifier assigned by ROOK during onboarding.
user_idThe identifier of the user associated with the document. This value is defined by your application.

Authentication​

Lab Data supports two authentication methods.

Bearer Token​

Recommended for new integrations.

Authorization: Bearer <your_cognito_token>
Basic Authentication​

Supported for existing ROOK integrations.

Authorization: Basic <base64(username:password)>

Request format​

Requests must be sent using multipart/form-data.

Form parameters​
FieldTypeRequiredDescription
fileFileYesLaboratory document in PDF, JPEG, or PNG format. Maximum file size: 10 MB.
timezoneStringYesUTC offset corresponding to the sample collection time. The value must use the ISO-8601 offset format.
Example request​
curl -X POST \
"https://api.lab.rook-connect.com/client_uuid/your-client-uuid/user_id/your-user-id" \
-H "Authorization: Bearer <your_token>" \
-F "file=@/path/to/laboratory_result.pdf" \
-F "timezone=-05:00"

Time zone​

Use the timezone field to specify the time zone associated with the sample collection date and time when it cannot be determined directly from the document.

ROOK determines the time zone using the following priority:

  1. The time zone identified in the document.
  2. The value provided in the timezone field.
  3. If neither is available, timestamps are returned without time zone information.

The value must be provided as an ISO-8601 UTC offset.

Valid valuesInvalid values
-05:00UTC
+01:00EST
Z-5:00

Response​

If the request is valid, the endpoint returns an HTTP 200 OK response.

{
  "document_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "received"
}

The document_id uniquely identifies the submitted document.

Store this identifier to correlate the submitted document with the processing results delivered through the Data Webhook.

Response codes​

Status codeDescription
200 OKThe document was successfully received and processing has started.
400 Bad RequestThe request is invalid or required fields are missing. Verify that both file and timezone are included and correctly formatted.
401 UnauthorizedAuthentication failed. Verify the credentials provided in the Authorization header.
403 ForbiddenLab Data is not enabled for your organization. Contact the ROOK team to enable the service.
413 Payload Too LargeThe uploaded file exceeds the maximum supported size of 10 MB.
415 Unsupported Media TypeThe request was not sent using multipart/form-data.
500 Internal Server ErrorAn unexpected error occurred while receiving the document. Retry the request. If the issue persists, contact ROOK Support.

After submitting a document​

Once the document is received, ROOK starts processing it asynchronously.

During processing, ROOK extracts biomarkers, normalizes the data, and performs the required validations before generating the structured result.

There is no endpoint to check the processing status.

When processing completes successfully, ROOK automatically sends the results to your configured Data Webhook.

If a document cannot be processed or is identified as a duplicate, no Data Webhook is sent. If you need assistance investigating one of these cases, provide the document_id returned when the document was submitted.

EHR/EMR Clinical Ready Beta​

The EHR/EMR Clinical Ready add-on transforms your users' normalized health summaries into a FHIR R4-compliant document, annotated with LOINC codes and UCUM units. Every time a new summary is generated or updated, ROOK consolidates the available health data and delivers a FHIR Bundle via your existing Data Webhook — no additional integration required.

How it works​

ROOK reads from three summary types and maps each metric that has a LOINC code into an Observation resource. Metrics without a LOINC code are excluded.

SourceClinical data included
body_summaryWeight, height, BMI, blood pressure, resting HR, SpO₂, caloric intake
physical_summarySteps, distance, average HR, VO₂max, SpO₂
sleep_summarySleep duration and stages, breathing rate, SpO₂, time to fall asleep

Each document is versioned: a new version is only generated when the clinical content actually changes. If no new data arrives, the existing document is preserved.

Payload structure​

The FHIR Bundle is delivered via webhook with data_structure: "clinical_ready". The bundle follows the FHIR R4 collection type and includes one Patient resource and one Observation per mapped metric.

{
  "version": 1,
  "document_version": 1,
  "data_structure": "clinical_ready",
  "user_id": "user123",
  "client_uuid": "client456",
  "clinical_ready": {
    "metadata": {
      "datetime_string": "2025-10-13T18:00:00.000Z",
      "user_id": "user123",
      "sources_of_data_array": ["Apple Health"],
      "fhir_export_ready": true,
      "fhir_export_completed_at": "2025-10-13T08:00:00.000Z"
    },
    "clinical_ready_data": {
      "resourceType": "Bundle",
      "id": "rook-clinical-bundle-user123",
      "type": "collection",
      "timestamp": "2025-10-13T18:00:00.000Z",
      "meta": {
        "profile": ["http://hl7.org/fhir/StructureDefinition/Bundle"],
        "source": "rook-clinical-normalization-engine",
        "tag": [
          {
            "system": "https://api.tryrook.io/fhir/tags",
            "code": "clinical_ready_export",
            "display": "client=client456 user=user123 fhir_export_ready=true"
          }
        ]
      },
      "entry": [
        {
          "fullUrl": "urn:uuid:patient-user123",
          "resource": {
            "resourceType": "Patient",
            "id": "patient-user123",
            "identifier": [
              {
                "system": "https://api.tryrook.io/users",
                "value": "user123"
              }
            ],
            "meta": { "source": "rook-clinical-normalization-engine" }
          }
        },
        {
          "fullUrl": "urn:uuid:obs-heart-rate-avg",
          "resource": {
            "resourceType": "Observation",
            "id": "obs-heart-rate-avg",
            "status": "final",
            "category": [
              {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                    "code": "vital-signs"
                  }
                ]
              }
            ],
            "code": {
              "coding": [
                {
                  "system": "http://loinc.org",
                  "code": "8867-4",
                  "display": "Heart rate"
                }
              ]
            },
            "subject": { "reference": "urn:uuid:patient-user123" },
            "effectivePeriod": {
              "start": "2025-10-13T00:00:00.000Z",
              "end": "2025-10-13T23:59:59.999Z"
            },
            "meta": { "source": "rook-clinical-normalization-engine" },
            "extension": [
              {
                "url": "https://api.tryrook.io/fhir/extensions/observation-context",
                "valueString": "daily_average"
              }
            ],
            "valueQuantity": {
              "value": 94,
              "unit": "beats/min",
              "system": "http://unitsofmeasure.org",
              "code": "/min"
            }
          }
        },
        {
          "fullUrl": "urn:uuid:obs-steps",
          "resource": {
            "resourceType": "Observation",
            "id": "obs-steps",
            "status": "final",
            "category": [
              {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                    "code": "activity"
                  }
                ]
              }
            ],
            "code": {
              "coding": [
                {
                  "system": "http://loinc.org",
                  "code": "55423-8",
                  "display": "Number of steps in unspecified time Pedometer"
                }
              ]
            },
            "subject": { "reference": "urn:uuid:patient-user123" },
            "effectivePeriod": {
              "start": "2025-10-13T00:00:00.000Z",
              "end": "2025-10-13T23:59:59.999Z"
            },
            "meta": { "source": "rook-clinical-normalization-engine" },
            "valueQuantity": {
              "value": 11701,
              "unit": "steps",
              "system": "http://unitsofmeasure.org",
              "code": "{steps}"
            }
          }
        },
        {
          "fullUrl": "urn:uuid:obs-sleep-duration",
          "resource": {
            "resourceType": "Observation",
            "id": "obs-sleep-duration",
            "status": "final",
            "category": [
              {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                    "code": "survey"
                  }
                ]
              }
            ],
            "code": {
              "coding": [
                {
                  "system": "http://loinc.org",
                  "code": "93832-4",
                  "display": "Sleep duration"
                }
              ]
            },
            "subject": { "reference": "urn:uuid:patient-user123" },
            "effectivePeriod": {
              "start": "2025-10-12T23:09:16.916Z",
              "end": "2025-10-13T05:17:17.486Z"
            },
            "meta": { "source": "rook-clinical-normalization-engine" },
            "valueQuantity": {
              "value": 21145,
              "unit": "s",
              "system": "http://unitsofmeasure.org",
              "code": "s"
            }
          }
        }
      ]
    }
  }
}
tip

The full bundle includes one Observation per mapped metric across all available summaries. The examples above illustrate the three Observation categories used: vital-signs (body metrics), activity (physical data), and survey (sleep data).

To activate the EHR/EMR Clinical Ready add-on for your integration, contact your ROOK account representative.

Medical Devices Beta​

The Medical Devices add-on is an optional module that, once activated, enriches supported events with a device_source_data_array object appended at the top level of each event. This object provides metadata about the physical device that captured the measurement.

Supported sources and events​

Data SourceSupported Events
Apple Healthbody_blood_glucose_event, body_blood_pressure_event, body_oxygenation_event, body_temperature_event, body_ecg_event
Withingsblood_pressure_event, temperature_event, oxygenation_event, ecg_event
Dexcomblood_glucose_event
Health Connectbody_blood_glucose_event, body_blood_pressure_event, body_oxygenation_event, body_temperature_event
Samsung Healthbody_blood_glucose_event, body_blood_pressure_event, body_oxygenation_event, body_temperature_event

device_source_data_array structure​

When the add-on is active, every supported event will include the following field at its top level:

"device_source_data_array": [
  {
    "device_type_string": "Activity Tracker",
    "manufacturer_string": "Withings",
    "medical_grade_bool": null,
    "model_string": "ScanWatch 2",
    "source_type_string": "wearable/sdk"
  }
]
FieldTypeDescription
device_type_stringstringCategory of the device (e.g., "Activity Tracker")
manufacturer_stringstringDevice manufacturer name
medical_grade_boolboolean | nullWhether the device is medical-grade certified
model_stringstringSpecific model name of the device
source_type_stringstringData source type (e.g., "wearable/sdk")

To activate the Medical Devices add-on for your integration, contact your ROOK account representative.

Branded Auth On Hold​

The Branded Auth add-on lets you customize the data source connection interface, removing ROOK's visual identity and replacing it with your own company's. This ensures that the end user perceives a native, consistent synchronization process within a trusted environment aligned with your brand.

By default, when users link their health devices or apps, they go through a standardized authentication flow. By enabling Branded Auth, you can:

  • Replace the ROOK logo with your own on all connection screens.
  • Maintain visual consistency at every step of the process, from selecting the data source to confirming synchronization.

To activate Branded Auth on your instance or request details about the technical customization requirements, please contact the ROOK support team or your account manager.

info

This process can take several weeks and partly depends on the timelines of the respective data sources. We strongly recommend starting early to avoid any delays to your launch.