Pre-shift and on-shift tracking

Introduction

The HyperTrack Orders API lets you track shifts throughout their lifecycle.

Pre-shift tracking enables you to preemptively monitor risk of no-call-no-shows or delays. This allows you to take mitigating actions like checking if the worker is able to make it OR informing the client of a late arrival OR finding a replacement worker if needed.

On-shift tracking enables you to understand how much time the worker spends at the destination and get automated updates if the worker exits the destination. All the entry and exits to the destinations are captured to help understand how much time the worker actually spent on site and when they finally left.

Both pre-shift and on-shift tracking come with HyperTrack's automated location outage reporting where we notify you if the worker's location is unavailable with actionable outage reasons so you can increase your tracking rates.

Worker Setup

To automatically track shifts using HyperTrack you must first complete your worker setup as described here.

📘

The worker app setup must integrate silent push notifications for iOS and Android. HyperTrack uses a combination of silent push notifications and sync method on the SDK to ensure that tracking starts and stops on the worker device as expected.

Pre-shift tracking

To track pre-shift risks you can call the HyperTrack Orders API tracking endpoint. Based on your business logic, you can decide how much in advance of the shift start time, you should start tracking the shift.

A few key important parameters for pre-shift tracking are listed below:

• Use your unique shift identifier like a shift_id to set the HyperTrack order_handle. This enables you to link shifts in your system to orders tracked in HyperTrack.
• Use the shift start time to set scheduled_at in HyperTrack. This defines the target time based on which HyperTrack will estimate delay risks using the worker live location and live traffic.
• Use polygon geofences if available for the order destination. If polygons are not available, you can use radial geofences. For recurring work places, create places in HyperTrack and use the place_handle as the order destination.
• To generate delay risks based on the scheduled_attime, destination, worker live location and real time traffic based ETA set track_mode as on_shift
• Use order metadata for key shift parameters to sort/filter/query data as needed.

The screenshot below shows the HyperTrack Order timeline for a shift that arrived late. As you can see the shift is scheduled for 10:10pm and tracking started at 10:00pm, but the worker was mocking location till 10:50pm. The worker arrived at 10:55pm which was 45 mins late for the shift.

Note that you can embed this view in your dashboard or use the webhooks for significant shift updates to incorporate key risks and updates in your own control tower.

Sample Orders API payloads to track pre-shift, on-shift or full-shift risks are provided here .

On-shift tracking

To track on-shift risks you can call the HyperTrack Orders API tracking endpoint. Typically on-shift tracking can be started ~30mins before the shift.

A few key important parameters you should keep in mind for on-shift tracking are listed below:

• Use your unique shift identifier like a shift_id to set the HyperTrack order_handle. This enables you to link shifts in your system to orders tracked in HyperTrack.
• Use the shift start time to set scheduled_at in HyperTrack. Note for on-shift tracking we do not compute delays since the assumption is that work has already commenced.
• Use the shift duration as the expected_service_time for the order. Note HyperTrack does not automatically close the order based on this parameter, but uses it as a reference.
• Use polygon geofences if available for the order destination. If polygons are not available, you can use radial geofences and improve them over time. For recurring work places, create places in HyperTrack and use the geofence_id as the order destination to auto-generate place intelligence.
• To track all geofence entry/exits and time spent inside the geofence based on the set track_mode as on_shift
• Use order metadata for key shift parameters to sort/filter/query data as needed.

The screenshot below shows the HyperTrack Order timeline for on-shift tracking. The shift was expected to start at 11:05AM and be for 4 hours. The worker reached on-time and spent the expected amount of time at the destination. During the shift the worker did exit the destination for a break a few times, but they returned and spent the expected amount of time on-site.

As with any timeline view, you embed this view in your dashboard or use webhooks to incorporate significant timeline updates in your own control tower.

Sample Orders API payloads to track pre-shift, on-shift or full-shift risks are provided here .

Sample Orders API payloads

The HyperTrack Orders API lets you track shifts throughout their lifecycle.

Sample payloads for pre-shift, on-shift and full-shift tracking are provided below.

{
    "ops_group_handle": "default",
    "track_mode": "pre_shift",
    "worker_handle": "[email protected]",
    "orders":
    [
        {
            "order_handle": "shift-1",
            "destination":
            {
                "address": "4501 Rosewood Dr, Pleasanton, CA 94588",
                "geometry":{
                    "type": "Point",
                    "coordinates": [-121.889965, 37.6982982]
                }
            },
            "scheduled_at": "2025-01-21T23:00:00Z"
        }
    ]
}

{
    "ops_group_handle": "default",
    "track_mode": "on_shift",
    "worker_handle": "[email protected]",
    "orders":
    [
        {
            "order_handle": "shift-2",
            "destination":
            {
                "address": "4501 Rosewood Dr, Pleasanton, CA 94588",
                "geometry":{
                    "type": "Point",
                    "coordinates": [-121.889965, 37.6982982]
                }
            },
            "expected_service_time": 10800
        }
    ]
}

{
    "ops_group_handle": "default",
    "track_mode": "full_shift",
    "worker_handle": "[email protected]",
    "orders":
    [
        {
            "order_handle": "shift-3",
            "destination":
            {
                "address": "4501 Rosewood Dr, Pleasanton, CA 94588",
                "geometry":{
                    "type": "Point",
                    "coordinates": [-121.889965, 37.6982982]
                }
            },
            "scheduled_at": "2025-01-21T23:00:00Z",
            "expected_service_time": 10800
        }
    ]
}

Add clock-in/out tags to your shift timeline

To add clock-in/out geotags to your shift timeline and track deviations from the expected locations please refer to this section.

Managing Shifts

You can manage shifts using the following operations of the Orders API:

Retrieve a shift timeline

To retrieve a shift timeline you can use the GET Order Timeline endpoint with the order_handle. This will return the full order timeline payload as described in the API. Note - for real time updates it is recommended to listen to webhooks.

Complete or Cancel a shift

Complete or Cancel shifts by calling the related endpoint of the Orders API.

📘

Note once you complete or cancel the shift and the worker has no more shifts or work remaining to be tracked, HyperTrack will automatically stop tracking the worker's device. This requires you to integrate silent push notifications on iOS and Android.

Update a shift

Update existing shifts whenever you need to modify attributes such as destination, scheduled_at or metadata.

Get real-time shift status updates on webhooks

For real time shift updates it is recommended to listen to webhooks.

Additional Resources

• Customizing your views: HyperTrack offers you options that allow you to create customizations for your views. You can find the details here .
• Embedding views in your dashboards: To learn about embedding our views in your dashboards please refer here.

Questions?

Please do not hesitate to contact us with your questions and feedback.