API Endpoints

Description

At Mercury, we use the following terms that are referred to throughout this document:

Users: These are the caregivers that log into the Mercury Alert app. They receive alerts and monitor devices.
Devices: These are the installed devices in homes and care facilities.
States: This is a description of how a monitored person can be at a particular point in time. The states we currently track are in_bed, away, stand, sit, fall.
Current state: This is the recorded state of a monitored person at the time the request is made.

User Endpoints

Create User

Option 1: Self-managed users
- We will onboard you as an app client in AWS Cognito.
- User creation is handled through an OIDC / SAML integration with AWS Cognito.
- All requests must have the X-API-KEY header with a valid API key.
- All requests must have the AWS Cognito token sent in the Authorization header.
Option 2: Mercury-managed users
- We will onboard you as an app client in AWS Cognito.
- Users are automatically added to the database upon account creation.
- All requests must have the X-API-KEY header with a valid API key.
- All requests must have the AWS Cognito token sent in the Authorization header.

Get User Information

Endpoint: /api/users/{user_id}
Method: GET
Description: Retrieve information about a specific user.
Example Response

{
    "name": "John Smith",
    "phone_number": "+15550001",
    "email": "johnsmith@email.com"
}

Get Devices for a User

Endpoint: /api/users/{user_id}/devices
Method: GET
Description: Retrieve a list of devices monitored by a specific user, along with their current status.
Example Response

{
    "devices": [
        {
            "device_id": "mercury-example-0",
            "name": "Bedroom",
            "current_state": "fall",
            "time_in_state_minutes": 10
        },
        {
            "device_id": "mercury-example-1",
            "name": "Dad",
            "current_state": "fall",
            "time_in_state_minutes": 1
        },
    ]
}

Device Endpoints

Get Device Information

Endpoint: /api/devices/{device_id}
Method: GET
Description: Retrieve information about a specific device.
Example Response

{
    "device_id": "mercury-example-1",
    "name": "Dad",
    "current_state": "fall",
    "time_in_state_minutes": 1
}

Get Caregivers for a Device

Endpoint: /api/devices/{device_id}/caregivers
Method: GET
Description: Retrieve a list of caregivers for a specific device.
Example Response

{
    "user_caregivers": [
        {
            "user_id": "ce689ddf-f359-4b9e-83ce-2d2dac44bbfa",
            "name": "John Smith",
            "email": "johnsmith@email.com",
            "phone_number": "+15550001"
        },
        {
            "user_id": "6b19fce6-31c8-4866-99a7-3ee4bfb8f423",
            "name": "Jane Doe",
            "email": "jane.doe1234@email.com",
            "phone_number": "+15550002"
        }
    ]
}

Get Owner for a Device

Endpoint: /api/devices/{device_id}/owner
Method: GET
Description: Retrieve the owner of a specific device.

{
    "user_owner": {
        "user_id": "ce689ddf-f359-4b9e-83ce-2d2dac44bbfa",
        "name": "John Smith",
        "email": "johnsmith@email.com",
        "phone_number": "+15550001"
    }
}

Alert Settings Endpoints

Get Alert Settings for a Device

Endpoint: /api/devices/{device_id}/{user_id}/alert-settings
Method: GET
Description: Retrieve alert settings for a specific device.
Example Response

{
    "is_daily_update_enabled": true,
    "is_offline_notification_enabled": true,
    "is_out_of_bed_notification_enabled": true,
    "is_sitting_notification_enabled": true,
    "is_in_bed_notification_enabled": true,
    "is_fall_notification_enabled": true,
    "is_automatic_notification_period_enabled": false, 
    "is_notifications_enabled": true,
    "is_standing_notification_enabled": false,
    "is_caregiver_two_way_audio_enabled": true,
    "is_leaving_room_notification_enabled": false,
    "notification_start_time": {
        "hour": 14,
        "minute": 23,
        "timezone": "US/Pacific"
    },
    "notification_end_time": {
        "hour": 14,
        "minute": 23,
        "timezone": "US/Pacific"
    }
}

Update Alert Settings for a Device

Endpoint: /api/devices/{device_id}/{user_id}/alert-settings
Method: PUT
Description: Update alert settings for a specific device.
Example Request

{
    "is_daily_update_enabled": true,
    "is_sitting_notification_enabled": true,
    "is_in_bed_notification_enabled": true,
    "is_fall_notification_enabled": true,
    "is_automatic_notification_period_enabled": false, 
    "is_notifications_enabled": true,
    "is_standing_notification_enabled": false,
    "is_caregiver_two_way_audio_enabled": true,
}

Analytics Endpoints

Get In/Out Bed Detections for the Last 7 Days

Endpoint: /api/analytics/state_history_7d/{device_id}
Method: GET
Description: Retrieve the last 7 days of states for a specific device. out_of_bed corresponds to a detection of either away or stand. The detections are grouped by the night date, i.e. the date in which the night started (e.g. 1 AM on 9/17/2024 has night date 9/16/2024).

{
    "2024-07-16": [
        {
            "night_date": "2024-07-16",
            "state": "in_bed",
            "start_time": "2024-07-16 23:58:45.193867",
            "end_time": "2024-07-17 00:23:45.193867",
            "duration_minutes": 25
        },
        {
            "night_date": "2024-07-16",
            "state": "out_of_bed",
            "start_time": "2024-07-16 23:58:45.193867",
            "end_time": "2024-07-17 00:23:45.193867",
            "duration_minutes": 25
        },
        ...
    ]
}

Get Safety Score

Endpoint: /api/analytics/safety_score_7d/{device_id}
Method: GET
Description: Retrieve the computed safety score over the last 7 days for a specific device.

{
    "2024-07-16": 92,
    "2024-07-15": 91,
    "2024-07-14": 36,
    "2024-07-13": 74,
    "2024-07-12": 88,
    "2024-07-11": 94,
    "2024-07-11": 53,
}

Get Top Hours Left Bed

Endpoint: /api/analytics/top_hours_left_bed_7d/{device_id}
Method: GET
Description: Retrieve the top hours (24 hour time) when a person left the bed for a specific device over the last 7 days.

{
    "top_times": [
        {
            "hour": 0,
            "percentage": 65
        },
        {
            "hour": 3,
            "percentage": 35
        }
    ]
}

Get Average Time Spent In Bed, Out of Bed, and Sitting (Last 7 Days)

Endpoint: /api/analytics/average_state_time_7d/{device_id}
Method: GET
Description: Retrieve the average time in minutes spent in bed, out of bed, and sitting for the last 7 days for a specific device.
Example Response

{
    "in_bed": 36,
    "out_of_bed": 192,
    "sitting": 12
}

Get Average Number of Times Getting In/Out of Bed and Sitting

Endpoint: /api/analytics/average_state_occurrences_7d/{device_id}
Method: GET
Description: Retrieve the average number of times over the past 7 days of getting in/out of bed and sitting for a specific device.

{
    "in_bed": 5,
    "out_of_bed": 2,
    "sitting": 1,
}

Get Averages Across All Devices

Endpoint: /api/analytics/population_state_averages
Method: GET
Description: Retrieve the nightly averages of in bed time, out of bed time, sitting time, in bed occurrences, out of bed occurrences, sitting occurrences, and safety score across all devices.

{
    "duration": {
        "in_bed_minutes": 100,
        "out_of_bed_minutes": 30,
        "sitting": 10,
    },
    "occurrences": {
        "in_bed": 5,
        "out_of_bed": 2,
        "sitting": 1,
    },
    "safety_score": 84
}