Why migrate to Orders API?

Orders API represents the next generation of our product, introducing new capabilities made possible by its improved architecture and implementation.

It offers more granular control and supports advanced shift-based workflows. This shift from mere tracking to comprehensive location intelligence represents a holistic approach to understanding and addressing proof of work. For TripsV1 customers, this is a major leap from being able to track a single shift to having the ability to create multi-shift use cases which are the need of the hour.

Here are some key features of the Orders API:

• Native NCNS (No-call No-show), Worker Left Early and other Order risk detection capabilities
• Orders now includes Clock-in/Clock-out signals to clearly define shift boundaries, aiding in better payout accuracy and dispute resolution. Combined with the new SDK, you can ensure that workers Clock-in/Clock-out only inside the destination boundary
• Automatic reports to monitor orders and tracking rate with location outage action reports to improve overall tracking health.
• API supports the use of Places that automatically handles geofence creations based on the defined Place. This integration provides customers with improved geofence shapes based on ground truth that helps improve fraud detection, provides better ETAs, and worker left early detections
• API supports automatic worker device management where Orders are moved between devices when the workers login to different devices and help detect fraudulent behavior
• Enhanced UI experiences with point in time ETAs and replay features

These enhancements make the Orders API a robust tool for managing workforce logistics with precision and insight.

Migration Steps

1. Migrate from Devices to Workers

For the Orders API, we've introduced the concept of a Worker. This is the person that is assigned a gig and goes to your customer location to complete the perform the service. A worker is associated with only one device at any given instance, but we now provide the ability for the worker to change their device seamlessly between shifts while ensuring their work is correctly attributed to them.

To learn more on how to set up your workers check out our Worker Setup guide.

In this step, you can create a worker for each device you currently have in the HyperTrack system and map them.

2. Create Places

The next step is to set up Places. The Places API allows you to create a place in HyperTrack that represents a customer location. Each place is uniquely identified by a place_handle, which serves as a reference to how your team identifies the customer location within your system.

A place can include key properties such as:

• Address: A human-readable location description.
• Coordinates: Latitude and longitude for precise mapping.
• Metadata: Additional attributes relevant to the customer location.

Setting up Places is crucial because the place_handle will be used as the destination for an Order in the next step. Additionally, configuring Places helps generate valuable insights as more activity occurs at a customer location. This includes:

• Automatic detection of parking zones and work areas.
• Fraud reduction by improving geofence accuracy.
• Operational insights based on recurring activity patterns

Please note that before an Order is created for a Place, the Place must exist. If the place is not setup yet, the Orders API will return a 400 that can be handled to create the missing Place.

POST /places/v1
{
  "place_handle":"apple_park",
  "address": "One Apple Park Way, Cupertino, CA 95014",
  "geometry": {
    "type":"Polygon",
    "coordinates":[[
      [-90.013951, 35.031187],
      [-90.013919, 35.030037],
      [-90.012792, 35.030037],
      [-90.012878, 35.031187],
      [-90.013951, 35.031187],
      [-90.013951, 35.031187],
      [-90.013951, 35.031187],
      [-90.013951, 35.031187],
      [-90.013951, 35.031187]
      ]]
    ]
  }
}

📘

If you don't have the coordinates for a place, the Places API will automatically infer a polygon geofence got the provided address. Refer to pricing here.

3. Migrate your API from Trips to Orders

With TripsV1, you used the following endpoints:

- POST /trips
- POST /trips/{trip_id}/complete
- GET /trips/{trip_id}
- GET /trips/{trip_id}/analytics
- GET /trips

Create Order with Orders API

To track and Order, update the endpoint from POST /trips to POST /order/track. Here are comparable samples of the payloads:

Note the new order_handle field that allows you to label the order using your business term for the shift and the destination is not the place_handle instead of coordinates.

Complete the Order

To complete an order being tracked, update the endpoint from POST /trips/{trip_id}/complete to POST orders/<order_handle>/complete.

Get Order data

To get the details of a single Order, update the endpoint from GET /trips/<trip_id> to GET /orders/<order_handle>

To get the list of all Orders with your choice of filtering, update the endpoint from GET /trips to GET /orders

To get analytics data for an Order, update the endpoint from GET /trips/<trip_id>/analytics to GET /orders/<order_handle>. This endpoint provides the active duration at destination, tracking rate, active duration and total duration of tracking during the lifetime of the Order.

📘

Orders API

There's so much more to do with the new Orders API, so please check the Orders API references

4. Enhance your workflows with Order webhooks

The only impact of this migration are the deprecation of trips webhooks for orders webhooks. The following list of webhooks are unchanged:

• location
• device_status
• battery
• trip
• reinstall
• registration_update

The mapping of the Trips API to Orders API are listed below:

Additionally you will also receive webhooks around Risks and Place boundary corrections.

📘

Webhooks

You can find more information on Order webhooks here

5. Migrate to the new UI

We've been chipping away at creating a much better UI experience for your Ops teams. If you are users of our embed and trckat views, you can make the changes below to get the latest experience with your Orders.

https://embed.hypertrack.com/trips/{trip_id}?publishable_key={your_key}

https://embed.hypertrack.com/views/orders/{order_handle}?publishable_key={your_key}

Here's what the new world looks like!

📘

New UI Experience

There are a lot more improved UI experiences for you Ops teams to adopt. Please take a look here for more information.

Voila! Following these steps will move you to the new HyperTrack world!

Migrations are hard and the HyperTrack team is with you every step of the way, so feel free to reach out to us and we'll ensure that your experience is as seamless as possible.