🚧

This section is for existing customers that already use Devices API and want to move to new Workers API

Introduction

Worker in HyperTrack is the Driver/Expert/Pro/Courier. Every worker has a worker_handle which you use internally to identify your mobile app users. For example, this could be the user_id, email, phone number etc. The worker_handle stays the same while the devices (device_ids) used by the worker might change over time. It is used in the Ops Views to display information about the work done by the worker.

So what's the big deal you ask? What can the Worker API do for me? Great question, let's answer that!

Workers are a high level construct you can use to interact with our APIs: where previously you would rely on device_id you now can use worker_handle. Previously you would have to keep track of your mobile app user’s device_id (subject to change) to know which one to start tracking for, but now you can simply start tracking for the worker_handle (remains the same).

For example, let’s say John has a device A. Tomorrow he switches his device to one that has B. Earlier, you would have to update the John’s linked device_id at your end from A to B to ensure that you start tracking the right device. With Workers you can forget about juggling the device_ids and instead use the worker_handle for all of your location tracking workflows.

Highlights of what this means in different contexts:

• Your Worker work timeline can be seamlessly retrieved even when the worker switches between devices.
  • Get worker timeline via GET https://v3.api.hypertrack.com/workers/{worker_handle}.
• You can now manage the worker availability and schedule to enable automatic start/stop tracking and order planning.
  • Set worker availability and schedule via PATCH https://v3.api.hypertrack.com/workers/{worker_handle}.
• You don’t need to manage device_ids on your backend. Use your own identifiers for workers as the worker_handle for tracking, availability, planning and searches.
• Nearby search can be used to find available workers for work.

So how do you start using workers?

Currently you probably manage device_ids in your own backend, correlating them with your mobile app user’s unique id (referred to as user_id onwards).

From the SDK, set metadata with worker_handle to your user_id and we’ll automatically create a worker with such handle for you. You can also pre-create workers via POST https://v3.api.hypertrack.com/workers, and the matching worker_handle will be updated with the new device_id (if the worker already exists).

Once this is done any future devices your user will have are going to be linked with that drive_handle. As long as your device metadata sets a worker_handle we will make sure the two linked.

Alternatively, you can create a worker POST https://v3.api.hypertrack.com/workers with a device_id in the body or patch existing workers with PATCH https://v3.api.hypertrack.com/workers/{worker_handle} with a device_id to link to the worker. But we recommend using the SDK approach, because you typically have the user_id readily available in your the app.