User

The User object represents the user who is being tracked. Every SDK instance needs to be initialised with a User to identify the tracking device.

User objects can belong to a Group object. User objects can be assigned Action objects.

Object properties

Property Type Description
id UUID string Unique identifier for the object
name string Name of the user
phone string E164 formatted phone number of user
group_id string The id of the fleet to which this user belongs
lookup_id string A unique id that you can add to the user to identify
availability_status string The availability status of the user, possible values are online, offline and active.
location_status string The location status of the user, possible values are location_available, location_disabled, location_permission_disabled and location_low_accuracy.
is_connected boolean Flag denoting the connection status of the user, possible values are true and false
pending_actions UUID array List of action ids that have been assigned to the user and are not complete
last_location JSON The last known location of the user with the speed, bearing, location accuracy and recorded time fields
last_heartbeat_at datetime Date time for last communication with the user's device
last_online_at datetime Date time when the last tracking session was started for the user
last_battery integer Battery percentage that was last recorded for the user
segments JSON array This the Placeline of the user i.e. a list of activity segments with location and other imp data points. Read this for more details
created_at datetime Timestamp of when user was created
modified_at datetime Timestamp of when user was last modified

API calls

Base url: https://api.hypertrack.com/api/v1/

API call Method URL Description
Create a user users/ Create a new user object
Retrieve a user users/ID/ Get an existing user object
Retrieve multiple users users/ Get multiple user objects, filtered by given params
Retrieve nearby users users/nearby/ List all users near a given location
Update a user users/ID/ Update an existing user object
Delete a user users/ID/ Delete an existing user object
Delete all users users/delete_all/ Delete all user objects (works only for test environment)
Assign actions to a user users/ID/assign_actions/ Assign actions to a user
Cancel actions of a user users/ID/cancel_actions/ Cancels all actions that have been assigned to that user
Complete actions of a user users/ID/complete_actions/ Completes all actions that have been assigned to that user
Stop tracking a user users/ID/stop_tracking/ Stop tracking the user.
Stop tracking for multiple users users/bulk_stop_tracking/ Stop tracking a list of users.

Availability statuses

Availability status Description
online When the user's session has been started with startTracking on the SDK
offline When the user's session has been ended by stopTracking on the SDK
active When the user has been assigned one or more Action - once the actions are completed, the user goes back to online

Location statuses

Location status Description
location_available When user location is available from the SDK
location_disabled When user has turned off location on his/her device
location_permission_disabled When user has denied location permission to your app
location_low_accuracy When user has denied location at high accuracy, or when user's device doesn't have high accuracy GPS

Connection status

This is denoted by User's is_connected object property.

Connection status Description
true When the device has network connectivity with the HyperTrack server
false When the device has lost network connectivity with the HyperTrack server

Create a User

This API will create and return a User object.

HTTP Request

POST https://api.hypertrack.com/api/v1/users/

Returns

Returns a user object if the call succeeded.

Parameters
Parameter Required Description
name No Name of the user
phone No E164 formatted phone number of the user
photo No A photo file of the user
lookup_id No A unique id that you can add to the user to search
group_id No The identifier of the group to which the user belongs

[warning] Lookup id behavior

If User with a given lookup_id already exists, then the existing user will be returned instead of creating a new one.

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"name\": \"User name\", \"phone\": \"+16502469293\"}" \
     https://api.hypertrack.com/api/v1/users/
hypertrack.User.create(
    name='Steve Smith',
    phone='+16502469293'
)
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
UserFactory userFactory = new UserFactory(client);
Map<String, Object> params = new HashMap<>();
params.put("name", "Steve Smith");
params.put("phone", "+16502469293");
User user = userFactory.create(params);
HyperTrack::User.create(name: "Steve Smith", phone: "+16502469293")
hypertrack.user.create({
    name: 'Steve Smith',
    phone: '+16502469293'
})

Assign Actions to a User

This API will assign a list of Action objects to a User.

HTTP Request

POST https://api.hypertrack.com/api/v1/users/<id>/assign_actions/

Returns

Returns a User object to which the actions are added.

Parameters
Parameter Required Description
action_ids Yes List of action ids to be assigned to the user
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"action_ids\": [\"6daacb03-6f02-4c60-b084-e9ffcd9eaf56\", \"37ae09b4-4801-48cb-bc50-99a7ee53f257\"]}" \
     https://api.hypertrack.com/api/v1/users/d0ae4912-2074-45ef-a7c0-76be58639ea9/assign_actions/
user = hypertrack.User.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9')
user.assign_actions(action_ids=['6daacb03-6f02-4c60-b084-e9ffcd9eaf56', '37ae09b4-4801-48cb-bc50-99a7ee53f257'])
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
UserFactory userFactory = new UserFactory(client);
User user = userFactory.retrieve("d0ae4912-2074-45ef-a7c0-76be58639ea9");

List<String> actionIds = Arrays.asList("6daacb03-6f02-4c60-b084-e9ffcd9eaf56", "37ae09b4-4801-48cb-bc50-99a7ee53f257");
userFactory.assignActions(user, actionIds);
user = HyperTrack::User.retrieve(user_id)
user.assign_actions({action_ids: ['6daacb03-6f02-4c60-b084-e9ffcd9eaf56', '37ae09b4-4801-48cb-bc50-99a7ee53f257']})
hypertrack.user
    .assignAction(
        "d0ae4912-2074-45ef-a7c0-76be58639ea9",
        {
            "action_ids": [
                "6daacb03-6f02-4c60-b084-e9ffcd9eaf56",
                "37ae09b4-4801-48cb-bc50-99a7ee53f257"
            ]
        }
    );

Cancel actions of a user

This API will cancel all actions have been assigned to a User.

HTTP Request

POST https://api.hypertrack.com/api/v1/users/<user-id>/cancel_actions/

Returns

Returns a user object if the call succeeded.

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     https://api.hypertrack.com/api/v1/users/<user-id>/cancel_actions/

Complete actions of a user

This API will complete all actions have been assigned to a User.

HTTP Request

POST https://api.hypertrack.com/api/v1/users/<user-id>/complete_actions/

Returns

Returns a user object if the call succeeded.

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     https://api.hypertrack.com/api/v1/users/<user-id>/complete_actions/

Retrieve a User

Retrieves a user object with the id.

HTTP Request

GET https://api.hypertrack.com/api/v1/users/<id>/

Returns

Returns a user object if a valid identifier was provided.

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v1/users/d0ae4912-2074-45ef-a7c0-76be58639ea9/
user = hypertrack.User.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9')
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
UserFactory userFactory = new UserFactory(client);
User user = userFactory.retrieve("d0ae4912-2074-45ef-a7c0-76be58639ea9");
HyperTrack::User.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9')
hypertrack.user
    .retrieve("d0ae4912-2074-45ef-a7c0-76be58639ea9")
    .then(function(user) {})

Update a User

Edit an existing user object.

HTTP Request

PATCH https://api.hypertrack.com/api/v1/users/<id>/

Returns

Returns the updated user object.

Parameters
Parameter Required Description
name No Name of the user
phone No E164 formatted phone number of the user
photo No URL of the photo to be assigned to the user
lookup_id No A unique id that you can add to the user to search
group_id No The identifier of the group to which the user belongs
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X PATCH \
     -d "{\"name\": \"User name\", \"phone\": \"+16502469293\"}" \
     https://api.hypertrack.com/api/v1/users/d0ae4912-2074-45ef-a7c0-76be58639ea9/
user = hypertrack.User.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9')
user.name = 'New name'
user.photo = 'https://photo-url.com/photo.png'
user.save()
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
UserFactory userFactory = new UserFactory(client);
User user = userFactory.retrieve("d0ae4912-2074-45ef-a7c0-76be58639ea9");

Map<String, Object> newParams = new HashMap<>();
newParams.put("name", "New name");
newParams.put("photo", "https://photo-url.com/photo.png");

userFactory.patch(user, newParams);
hypertrack.user
    .update(
        "d0ae4912-2074-45ef-a7c0-76be58639ea9",
        {
            "name": "New name",
            "photo": "https://photo-url.com/photo.png"
        }
    );

Delete a User

Delete an existing user object.

HTTP Request

DELETE https://api.hypertrack.com/api/v1/users/<id>/

Returns

Empty response if the object is deleted.

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X DELETE \
     https://api.hypertrack.com/api/v1/users/d0ae4912-2074-45ef-a7c0-76be58639ea9/
user = hypertrack.User.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9')
user.delete()
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
UserFactory userFactory = new UserFactory(client);
User user = userFactory.retrieve("d0ae4912-2074-45ef-a7c0-76be58639ea9");
userFactory.delete(user);
hypertrack.user
    .remove("d0ae4912-2074-45ef-a7c0-76be58639ea9");

List nearby Users

List all users near a given location ([latitude,longitude] or an action's expected_place). The users are returned in the order of their distance to the location of interest. This API can be used to find the best user to be assigned to an action.

HTTP Request

GET https://api.hypertrack.com/api/v1/users/nearby/

Returns

Returns a list of users, in the order of distance to the location.

Parameters
Parameter Required Description
action_id One of action_id or location is required Action id to get nearby users from that action's expected place
location One of action_id or location is required longitude,latitude to get nearby users from that location
id No List of user ids in comma separated format. Filter results to list of user ids specified in the request.
lookup_id No Filter user results by lookup id.
group_id No Filter user results by group id.
# Nearby with action_id
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v1/users/nearby/?action_id=ACTION_ID

# Nearby with location and restrict result to set of Users ids.
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v1/users/nearby/?location=longitude,latitude&id=user_id_1,user_id_2,...

List all Users

List all user objects. The list can be filtered using the following parameters.

HTTP Request

GET https://api.hypertrack.com/api/v1/users/

Returns

Returns a list of users.

Parameters
Parameter Required Description
page_size No Maximum number of objects to return, default is 50
name No Filter users with names that contain this string
id No Filter users with a comma separated list of ids
group_id No Filter user objects by group
lookup_id No Filter user objects by lookup id
last_location__bbox No Filter user objects within a bounding box. Specified as max_lng,max_lat,min_lng,min_lat
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v1/users/
users = hypertrack.User.list()
hypertrack.user
    .list()
    .then(function(users){});
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
UserFactory userFactory = new UserFactory(client);
HyperTrackArrayList<User> users = userFactory.list();
HyperTrack::User.list

Delete all Users in test environment

Delete all users, if its in test environment. If it is in production then all users cannot be deleted in a single API call. The API has no paramters and returns status 200 if successful.

HTTP Request

DELETE https://api.hypertrack.com/api/v1/users/bulk_delete/

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X DELETE \
     https://api.hypertrack.com/api/v1/users/bulk_delete/

Stop tracking user

You can use this API to call stop tracking from the backend. This requires a network connection on the device. Data recorded after the point when stop tracking is called will be ignored.

Condition Result
Push configured and network is available SDK will stop tracking
Push configured and network is unavailable SDK will stop tracking when the network comes back up
Push not configured SDK will stop tracking when it is makes a network call to the server
HTTP Request

POST https://api.hypertrack.com/api/v1/users/USER_ID/stop_tracking/

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     https://api.hypertrack.com/api/v1/users/USER_ID/stop_tracking/

Stop tracking for multiple users

You can use this API to call stop tracking from the backend. This requires a network connection on the device. Data recorded after the point when stop tracking is called will be ignored.

Condition Result
Push configured and network is available SDK will stop tracking
Push configured and network is unavailable SDK will stop tracking when the network comes back up
Push not configured SDK will stop tracking when it is makes a network call to the server
HTTP Request

POST https://api.hypertrack.com/api/v1/users/bulk_stop_tracking/

Request body
Parameters Description
user_ids List of user uuids. If not specified, then all users on the account stop tracking
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     https://api.hypertrack.com/api/v1/users/bulk_stop_tracking/

results matching ""

    No results matching ""